Fifty: Elektronik/FIFTY Elektronik (PS_Computer_Vertrieb).iso/ps8/fty1031/cport.doc

Text File | 1993-11-06 | 187.0 KB | 5,568 lines

            Cport

            Serial Communications Library for C/C++
            Version 2.0







   Copyright (c) 1993  Bri Productions - all rights reserved

   Cport is a registered trademark of Bri Productions. All other product and
   brand names are trademarks or registered trademarks of their respective
   holders.

                                 i


Contents
========

   Introduction
   ------------
      General Description ............................. 1-1
      Disclaimer ...................................... 1-2
      Evaluation Copy ................................. 1-2
      Purchase Version ................................ 1-2
      Contacting  Bri Productions ..................... 1-2
      Terminology ..................................... 1-3

   Using Cport
   -----------
      Basics .......................................... 2-1
      Buffered Input .................................. 2-3
      Buffered Output ................................. 2-5
      Handshaking ..................................... 2-7
      Direct Transmit Mode ............................ 2-10

   Theory of Operation
   -------------------
      The UART ........................................ 3-1
      The Transmitter and Receiver .................... 3-1
      The Transmit and Receive Queues ................. 3-2
      Input and Output Functions ...................... 3-2
      Control and Status Functions .................... 3-2
      Direct Transmit mode ............................ 3-2

   C Reference
   -----------
      Typedefs and Structures ......................... 4-1
         COM .......................................... 4-2
         CPARAM ....................................... 4-2
         byte ......................................... 4-3

      Global Variables ................................ 4-4
         comopen_errno ................................ 4-4

      Control Functions ............................... 4-5
         ComOpen ...................................... 4-6
         ComOpenS ..................................... 4-8
         ComClose ..................................... 4-8
         ComCloseAll .................................. 4-9
         ComHandshake ................................. 4-9
         ComParam ..................................... 4-10
         ComBaud ...................................... 4-11
         ComMode ...................................... 4-12
         ComRxQ ....................................... 4-13
         ComTxQ ....................................... 4-14
         ComTx ........................................ 4-15
         ComNS550 ..................................... 4-15
         ComTurbo ..................................... 4-16

                                 ii


      Input Functions ................................. 4-18
         ComGetc ...................................... 4-19
         ComGets ...................................... 4-19
         ComIn ........................................ 4-20
         ComFlushRx ................................... 4-21
         ComLenRx ..................................... 4-22
         ComPeek ...................................... 4-22
         ComRxScan .................................... 4-23

      Output Functions ................................ 4-25
         ComPutc ...................................... 4-26
         ComPuts ...................................... 4-26
         ComOut ....................................... 4-27
         ComFlushTx ................................... 4-28
         ComLenTx ..................................... 4-29
         ComTxWait .................................... 4-29

      Status Functions ................................ 4-31
         ComError ..................................... 4-32
         ComStatus .................................... 4-33
         ComRts ....................................... 4-33
         ComDtr ....................................... 4-34
         ComOut1 ...................................... 4-35
         ComUart ...................................... 4-35

      Data Integrity .................................. 4-37
         ComChecksum .................................. 4-38
         ComCrc16 ..................................... 4-38
         ComCrc32 ..................................... 4-39

      Misc Functions .................................. 4-41
         ComSetBreak .................................. 4-42
         ComClrBreak .................................. 4-42
         ComPutScrtch ................................. 4-43
         ComGetScrtch ................................. 4-43

   C++ Reference
   -------------
      Control Functions ............................... 5-1
         Cport::Cport ................................. 5-2
         Cport::operator int .......................... 5-4
         Cport::Handshake ............................. 5-5
         Cport::Param ................................. 5-6
         Cport::Baud .................................. 5-6
         Cport::Mode .................................. 5-7
         Cport::RxQ ................................... 5-8
         Cport::TxQ ................................... 5-9
         Cport::Tx .................................... 5-10
         Cport::NS550 ................................. 5-10
         Cport::Turbo ................................. 5-11

                                 iii


      Input Functions ................................. 5-13
         Cport::Get ................................... 5-14
         Cport::In .................................... 5-15
         Cport::FlushRx ............................... 5-16
         Cport::LenRx ................................. 5-17
         Cport::Peek .................................. 5-17
         Cport::RxScan ................................ 5-18

      Output Functions ................................ 5-19
         Cport::Put ................................... 5-20
         Cport::Out ................................... 5-21
         Cport::FlushTx ............................... 5-22
         Cport::LenTx ................................. 5-22
         Cport::TxWait ................................ 5-23

      Status Functions ................................ 5-24
         Cport::Error ................................. 5-25
         Cport::Status ................................ 5-25
         Cport::Rts ................................... 5-26
         Cport::Dtr ................................... 5-27
         Cport::Out1 .................................. 5-28
         Cport::Uart .................................. 5-28

      Data Integrity .................................. 5-29
         Cport::Checksum .............................. 5-30
         Cport::Crc16 ................................. 5-30
         Cport::Crc32 ................................. 5-31

      Misc Functions .................................. 5-33
         Cport::SetBreak .............................. 5-34
         Cport::ClrBreak .............................. 5-34
         Cport::Scratch ............................... 5-35

   File Transfer
   -------------
      Xmodem .......................................... 6-1
      XmodemTx ........................................ 6-2
      XmodemRx ........................................ 6-3
      Xcallback ....................................... 6-4
      Callback Function ............................... 6-5
      Xmodem Tables of Values ......................... 6-7

   Appendix
   --------
      Appendix A - Tables of Values ................... A-1
      Appendix B - Compiling and Linking .............. B-1
      Appendix C - Order form ......................... C-1

                                 1-1


Introduction
============

   General Description
   -------------------
      Cport is a general purpose C/C++ serial communications library for
      80x86 Intel processor-based systems and the National Semiconductor
      family of UARTs. This includes IBM and compatible computers and
      potentially 80x86 processor-based embedded applications. The latter
      is usually possible with few no modifications.

      Cport features:
         ■ Support for COM 1 to COM 4 and custom configurations
         ■ Simultaneous serial communications.
         ■ Baud rates from 50 to 115200 baud.
         ■ Built-in hardware and software handshaking.
         ■ Both transmitter and receiver are interrupt-driven.
         ■ Adjustable transmit and receive queues.
         ■ Queues as large as 65534 bytes each.
         ■ Transmit and receive queues are handled internally.
         ■ Supports the NS16550 UART automatically.
         ■ Developed in assembly language for optimum speed and efficiency.

      Cport provides a middle level C/C++ interface for general purpose
      serial communications. The library is lean and fast, so as to
      provide programs with high performance serial communications without
      significantly increasing its size. Cport can be used to develop
      higher level interfaces for specific types of serial devices or as
      is for more generic types of serial communications applications. An
      example of a higher level interface might be a set of functions
      that communicate with a serial printer. This interface would have
      more knowledge of the type of data, controls codes, protocol, etc.
      that relate to a serial printer. An example of a more generic
      application would be a terminal program since, like Cport, a
      terminal program is indifferent to the actual significance of the
      data.

      The design philosophy of Cport is to provide as many features
      as possible without hindering its most important attributes: speed
      and size. Many of the details, in addition to the actual hardware
      interface itself, are provided in order to facilitate serial
      communications software development. This includes the internal
      buffering (queues), hardware and software handshaking and different
      flavors of input/output functions. These features would either need
      to be implemented externally anyway, or do not add overhead unless used.

      Many features, such as timeouts, can additionally be easily implemented
      as needed at the middle, C/C++ level. Many techniques and features are
      demonstrated in the next section (Using Cport) and in examples
      throughout this document. Examples and techniques will continue
      to be compiled and made available in the future.

                                 1-2



   DISCLAIMER
   ----------
      Cport is provided AS IS. Bri Productions specifically disclaims any
      and all warranties, expressed or implied, including but not limited
      to any implied warranties including fitness for a particular purpose.
      Use this product at your own risk.


   Evaluation Copy
   ---------------
      This is an evaluation copy of Cport. This evaluation copy is
      provided to you at no charge* so that you may properly evaluate Cport
      prior to purchasing it. This evaluation copy has a fully functional
      small model library and contains no cripples. Redistribution of this
      evaluation copy, unaltered and without charge, is encouraged.

      We feel it is important that you be able to try a product prior
      to paying for it. This ensures that you will be able to determine
      the quality of a product and if it fits your needs. It avoids
      the hassle of money back guarantees which would otherwise waste
      your time and ours.

      We also feel that the producers of a product are entitled to be
      compensated for their hard work. This enables them to continue to
      provide a high quality product. If you intend to use Cport beyond
      the purpose evaluation, you are obligated to purchase a license.

      * Disk distributors may charge a minimum (reasonable) fee for
      distribution of this evaluation copy.


   Licensing
   ---------
      When you purchase a license for Cport, you will receive the small,
      medium, compact, large and huge model libraries; Library source code;
      Printed manual; and examples. You will also be entitled to
      technical support and low cost upgrades. When you license Cport you
      may incorporate any part of it into your own executable programs
      without additional royalties as long as they bear your own valid
      Copyright notice. Each lisense covers usage by a single person at a
      time. An order form is provided in Appendix C.


   Contacting  Bri Productions
   ---------------------------
      Bri Productions may be contacted by any of the following means:

              Telephone: [phone]

             CompuServe: 76635,2246

              U.S. mail: Bri Productions
                         39120 Argonaut Way, Ste 772
                         Fremont, CA 94538-1378

                                 1-3


   Terminology
   -----------
      This section defines some of the terminology used in this and other
      Cport documentation.

      The 'computer' refers to the machine on which Cport is running.
      'Remote device' refers to the device the computer is communicating
      with. The actual device may be a modem, serial printer or other
      communications device.

      If a serial port is, 'open' it is currently performing or ready to
      perform serial communications. All 'open' serial ports have a 'handle'
      which is assigned when it is 'opened'. This 'handle' is passed to Cport
      functions in order to identify the 'open' serial port the function is to
      act upon. (In C++, instances of the Cport class are used instead of
      handles).

      Individual units of 'data' that are transmitted and received may be
      referred to as 'characters' or 'bytes'. Technically, there is no
      difference between 'characters' and bytes, however; 'characters'
      usually refer to 7 or 8 bit ASCII values and 'bytes' typically refer to
      8 bit binary data. 'Data' refers to 'characters'/'bytes' in general.

      A 'signal' may refer to software (i.e. control characters) as well
      as actual hardware lines. This mainly refers to XON (ctrl-Q) and
      XOFF (ctrl-S), which are used in software handshaking. 'Signals' may
      be either inputs or outputs. A 'signal' is said to be 'asserted' if
      it is in a true/on state and 'inhibited' if it is in a false/off
      state. This stems from the idea that a 'signal' can be used to allow
       (assert) or preclude (inhibit) something such as the transmission of
      'data'.

                                 2-1


Using Cport
===========

   Basics
   ------
      Before a serial port can be accessed, it must be opened. The open
      functions identify the serial port by it's port address and
      interrupt request line. The parameter id contains the port base
      address in the lower 12 bits and the irq number in the upper 4 bits
      of id. The open functions also take parameters that describe the
      baud rate, word length, number of stop bits, parity check, and
      transmit and receive queue sizes. If a serial port is successfully
      opened, a handle to the newly opened serial port is returned to the
      caller. This handle is used to reference the serial port in
      subsequent calls to Cport functions. (C++ uses instances of the
      Cport class instead of handles). If the serial port cannot be
      opened, the open function returns NULL and sets the global variable
      'comopen_errno' to an error code. (C++ uses an int typecast instead
      of the global variable to hold the error code).

      Before a program terminates, the serial port must be closed to make
      certain restorations. Failing to close a serial port will leave
      these restorations undone and almost certainly cause the system to
      lock up. In C++, the serial port is closed automatically when it goes
      out of scope (destructor).


                                 2-2


      C Example:

            #include <stdio.h>
            #include "cport.h"

            int main(void)
            {
            COM com;      /* declare a serial port handle */

                  /* Open the serial port and get/store the serial port handle
                  */
               com = ComOpen(COM1, B9600, W8|S1|NONE, 1024, 512);


                  /* Check for a NULL handle. If the handle is NULL check
                  // comopen_errno for the cause
                  */
               if(com == NULL)
               {
                  puts("ERROR: unable to open serial port");
                  return(comopen_errno);
               }

                  /* Put a string to the newly opened serial port
                  */
               ComPuts(com, "Hello Cport");

                  ... The rest of the program here

                  /* Close the serial port before exiting
                  */
               ComClose(com);
               return(0);
            }

      C++ Example:

            #include <iostream.h>
            #include "cport.h"

            int main(void)
            {
               Cport com(COM1, B9600, W8|S1|NONE, 1024, 512);
               if((int)com != NO_ERR)   // uses int typecast
               {
                  cout << "ERROR: unable to open serial port" << endl;
                  return(com);
               }
               com.Put("Hello Cport");

                  ... The rest of the program here

               // The serial port is closed automatically by
               // the destructor.

               return(0);
            }

                                 2-3


   Buffered Input
   --------------
      When data is received, it is placed into the receive queue and stays
      there until an input function retrieves it. Input functions will
      only fetch whatever data is existing in the receive queue at
      the time the input function is called. If a specified length of data
      is expected, the receive queue can be queried to determine if enough
      data is available to call an input function. This is a common case
      with serial devices that send specific length messages terminated
      by a specific character (often '\n' or '\r'). In the examples, the
      function fetches a message only if one is available. If the message
      is not available, it returns a zero, If a message is available, the
      measurement is copied to the caller's buffer and a 1 is returned.

      C Example:

            #define   MSG_LEN      24
            #define   TERM_C      '\n'

            int GetMessage(COM com, char *buf)
            {
               if(ComLenRx(com) > MSG_LEN)
               {
                  ComGets(com, buf, MSG_LEN, TERM_C);
                  return(1);
               }
               return(0);
            }

      C++ Example:

            #define   MSG_LEN   24
            #define   TERM_C   '\n'

            int GetMessage(Cport& com, char *buf)
            {
               if(com.LenRx() > MSG_LEN)
               {
                  com.Get(buf, MSG_LEN, TERM_C);
                  return(1);
               }
               return(0);
            }

      If the messages are not of a specific length, the receive queue can
      be scanned for a particular character, namely the termination
      character. Scanning for a character is also possible with specific
      length messages but is slower than checking the length of the
      receive queue. In the following examples, the function fetches a
      message only if one is available. If the message is not available it
      returns a zero, If a message is available, the measurement is
      copied to the caller's buffer and a 1 is returned. If the message
      is longer that the specified maximum message length, a -1 is
      returned.

                                 2-4


      C Example:

            #define   MAX_MSG_LEN      80
            #define   TERM_C            '\n'

            int GetMessage(COM com, char *buf)
            {
            int len;

               len = ComRxScan(com, TERM_C);
               if(len > MAX_MSG_LEN)
                  return(-1);

               else if(len > 0)
                  ComGets(com, buf, MAX_MSG_LEN, TERM_C);

               return(len != 0);
            }

      C++ Example:

            #define   MAX_MSG_LEN      80
            #define   TERM_C            '\n'

            int GetMessage(Cport& com, char *buf)
            {
            int len;

               len = com.RxScan(TERM_C);
               if(len > MAX_MSG_LEN)
                  return(-1);

               else if(len > 0)
                  com.Get(buf, MAX_MSG_LEN, TERM_C);

               return(len != 0);
            }

      The previous examples are ideal for event driven routines. They do
      not wait for a message to be received if one is not ready.
      This allows a program to process other tasks instead of holding up
      program execution while waiting for a message. On the contrary, one
      may want to wait for a message, perhaps within a certain time frame.
      Revisiting the first example, we can add a timeout using the ANSI C
      compatible function, clock.

                                 2-5


      C Example:

            #include <time.h>
            #define   MSG_LEN      24
            #define   TERM_C      '\n'

            int GetMessage(COM com, char *buf, clock_t timeout)
            {
               timeout += clock();
               while(ComLenRx(com) <= MSG_LEN)
               {
                  if(clock() > timeout)
                     return(0);
               }
               ComGets(com, buf, MSG_LEN, TERM_C);
               return(1);
            }

      C++ Example:

            #include <time.h>
            #define   MSG_LEN   24
            #define   TERM_C   '\n'

            int GetMessage(Cport& com, char *buf, clock_t timeout)
            {
               timeout += clock();
               while(com.LenRx() <= MSG_LEN)
               {
                  if(clock() > timeout)
                     return(0);
               }
               com.Get(buf, MSG_LEN, TERM_C);
               return(1);
            }

   Buffered Output
   ---------------
      When an output function inserts data into the transmit queue, it
      does not wait for the data to be transmitted before the function
      returns. Instead the transmitter will subsequently remove the data,
      one byte/character at a time, in the order in which it was inserted and
      transmit them in the background. This allows the program to continue
      with more important tasks instead of waiting for the data to
      transmit at a relatively slow rate (compared to the processor).

      At certain points in a program, one may want to ensure that all the
      data thus far has been transmitted. To do this the transmit queue
      can be queried to determine how many bytes/characters still reside
      there. The following examples make sure all data finishes
      transmitting before the program is terminated.

                                 2-6


      C Example:

            int main(void)
            {
            COM com;

               com = ComOpen(COM2,B9600,W8|S1|NONE,512,2048);
               if(com == NULL)
                  return(comopen_errno);

               ComPuts(com, "Welcome to Bri Productions");
               while(ComLenTx(com) != 0);
               ComClose(com);
               return(0);
            }

      C++ Example:

            int main(void)
            {
               Cport com(COM2, B9600, W8|S1|NONE, 512, 2048);
               if((int)com != NO_ERR)
                  return(com);

               com.Put("Welcome to Bri Productions");
               while(com.LenTx() != 0);

               // The serial port is closed automatically by
               // the destructor.
               return(0);
            }

      Querying the transmit queue can also be useful in determining if
      there is enough room for new data. In the following, example a
      message is sent only if there is enough room for the whole message.
      The value returned should always be 0 (if not enough room) or the
      length of the message (number of characters put by ComPuts).

      C Example:

            #include <string.h>
            #define   TXSIZE   1024

            int PutMessage(COM com, const char *buffer)
            {
               if(TXSIZE - ComLenTx(com) < strlen(buffer))
                  return(0);

               return(ComPuts(com, buffer));
            }

                                 2-7


       C++ Example:

            #include <string.h>
            #define   TXSIZE   1024

            int PutMessage(Cport& com, const char *buffer)
            {
               if(TXSIZE - com.LenTx() < strlen(buffer))
                  return(0);

               return(com.Put(buffer));
            }

      If the transmit queue length is not checked and an output function
      is called without enough room for all the data, the number of
      byte/characters that did fit is returned. This value can be used
      as an offset into the data to determine the first byte/character
      that there was no room for. The following examples will not return
      until all the characters in the message are put to the queue.

      C Example:

            void PutMessage(COM com, const char *buffer)
            {
            const char *_buffer = buffer;

               while(*_buffer != '\0')
                  _buffer += ComPuts(com, _buffer);
            }

      C++ Example:

            void PutMessage(Cport& com, const char *buffer)
            {
            const char *_buffer = buffer;

               while(*_buffer != '\0')
                  _buffer += com.Put(_buffer);
            }


   Handshaking
   -----------
      There are number of built-in options available for implementing
      handshaking. The options can be divided into two categories. One is
      hardware handshaking and the other is software handshaking. In
      hardware handshaking, one or more of the hardware lines is used.
      In software handshaking, XON and XOFF characters are used.

                                 2-8


   Hardware Handshaking
   --------------------
      In hardware handshaking, any combination of the hardware signals
      RTS, DTR, DSR, CTS, and DCD can be used to achieve handshaking. RTS
      and/or DTR are used by the receiver to signal the remote device to
      suspend or resume transmitting. Similarly, DSR, CTS, and/or DCD can
      be used by the remote device's receiver to signal the transmitter to
      suspend or resume transmitting.

   Software Handshaking
   --------------------
      In software handshaking, the control characters XON (ctrl-Q) and
      XOFF (ctrl-S) are used to achieve handshaking. When receiver
      software handshaking (S_RX) is enabled, XON and XOFF characters are
      transmitted to signal the remote device to suspend or resume it's
      transmission. Notice that even though the XON and XOFF characters
      are sent by the transmitter, it is the receiver that exercises the
      handshaking in order to preclude a receive queue overflow. In
      transmit software handshaking (S_TX), the remote device sends XON
      and XOFF characters to suspend and resume the computer's
      transmission. Notice that even though the XON and XOFF characters
      are received, it is the transmitter that is affected. Both receive
      and transmit handshaking can be enabled simultaneously.

   The Receiver
   ------------
      When receive software (S_RX) and/or hardware handshaking (DTR and/or
      RTS) are enabled, the receiver monitors the length of the receive
      queue. If the length exceeds the specified threshold, the receiver
      will take the appropriate action to signal the remote device to
      suspend transmitting. When the length of the receive queue
      subsequently falls below half of the set threshold, the appropriate
      action is taken to signal the remote device to resume transmitting.

   The Transmitter
   ---------------
      When transmit software (S_TX) and/or hardware handshaking (DSR, CTS,
      and/or DCD) are enabled and the computer is signaled to suspend
      transmitting with the corresponding handshaking enabled, the
      transmitter will stop transmitting. Subsequently, when the computer
      is signaled to resume transmitting, the transmitter will pick up
      where it left off.

   User Handshaking
   ----------------
      Another option for implementing handshaking is for the programmer to
      implement their own handshaking scheme. To accomplish this, Cport
      provides the function ComTx. ComTx allows the programmer to turn the
      transmitter on and off. When the transmitter is turned off,
      transmitting halts immediately. If any characters still reside in
      the transmit queue, they will remain there until the transmitter is
      turned back on or the transmit queue is flushed. More characters may
      be put into the transmit queue while the transmitter is turned off.

                                 2-9


   Cooperation
   -----------
      In any handshaking scheme, it is imperative that the computer and
      the remote device recognize the same handshaking scheme. For
      instance, if the remote device recognizes hardware handshaking and
      the computer does not, the computer will ignore any requests by the
      remote device to suspend transmitting. If the remote device
      recognized software handshaking and the computer did not, bogus XON
      and XOFF characters might corrupt the received data.

      In the first example, the transmitter will not transmit unless CTS
      and DSR are asserted. The receiver will inhibit RTS if the receive
      queue exceeds 768 bytes/characters and assert it when it
      subsequently falls below 768 / 2. In the second example, the
      transmitter will stop if an XOFF character is received and restart
      when an XON character is received. If the receive queue length
      exceeds 768 bytes/characters, an XOFF character will be transmitted
      and when the length subsequently falls below 768 / 2, an XON
      character is transmitted.

      C Example 1

            int main(void)
            {
            COM com;

               com = ComOpen(COM1, B9600, W7|S1|EVEN, 1024,256);
               if(com == NULL)
                  return(comopen_errno);

               ComHandshake(com, CTS | DSR | RTS, 768);

               /* rest of the program */

               ComClose(com);
               return(0);
            }


      C++ Example 1

            int main(void)
            {
               Cport com(COM1, B9600, W7|S1|EVEN, 1024, 256, CTS|DSR|RTS, 768);
               if((int)com)
                  return(com);

               // rest of the program
               return(0);
            }

                                  2-10


      C Example 2

            int main(void)
            {
            COM com;

               com = ComOpen(COM1, B9600, W7|S1|EVEN, 1024, 256);
               if(com == NULL)
                  return(comopen_errno);

               ComHandshake(com, SOFT, 768); /* SOFT == S_RX | S_TX */

               /* rest of the program */

               ComClose(com);
               return(0);
            }

      C++ Example 2

            int main(void)
            {
                                                      // SOFT == S_RX | S_TX
               Cport com(COM1, B9600, W7|S1|EVEN, 1024, 256, SOFT, 768);
               if((int)com)
                  return(com);

               // rest of the program

               return(0);
            }

   Direct Transmit Mode
   --------------------
      In direct transmit mode, data is sent directly to the serial port.
      The output functions will only return after all the data has been
      transmitted or when a handshaking signal is inhibited. Direct mode
      is ideal for transmit intensive routines such as file transfers, where
      the main task is transmitting data. Otherwise direct transmit mode
      is not normally preferred.

      There are two ways to get into direct transmit mode. The first is to
      set the transmit queue size in the call to the open function (or
      constructor in C++) to zero. This method sets direct transmit mode
      permanently. To set direct transmit mode temporarily, turn the
      transmitter off with ComTx with the TX_DIRECT option.

                                 2-11


      C Example 1

            int main(void)
            {
            COM com;

                  /* transmit queue 0 = direct transmit mode
                   */
               com = ComOpen(COM1, B9600, W8 | S1 | NONE, 4096, 0);
               if(com == NULL)
                  return(comopen_errno);

                  /* continued   */

               ComClose(com);
               return(0);
            }



      C++ Example 1

            int main(void)
            {
                  // transmit queue 0 = direct transmit mode

               Cport com(COM1, B9600, W8 | S1 | NONE, 4096, 0);

                  // continued

               return(0);
            }

      In this examples, the transmitter is put into direct mode while a
      block of data is transmitted. The transmitter is subsequently
      restored to its previous state. The block of data is completely
      transmitted before the function returns (assumes no transmit
      handshaking is enabled).

      C Example 2

            #define BLOCK_SIZE   1024

            int SendBlock(COM com, byte *block)
            {
            int tx, rv;

               tx = ComTx(com, OFF | TX_DIRECT);
               rv = ComOut(com, block, BLOCK_SIZE);
               ComTx(com, tx);
               return(rv);
            }

                                 2-12


      C Example 2

            #define BLOCK_SIZE   1024

            int SendBlock(Cport& com, byte *block)
            {
            int tx, rv;

               tx = com.Tx( OFF | TX_DIRECT);
               rv = com.Out(block, BLOCK_SIZE);
               com.Tx(tx);
               return(rv);
            }


   Handshaking in Direct Transmit Mode
   -----------------------------------
      Transmit handshaking works a bit differently in direct transmit
      mode. In normal transmit handshaking, output functions will always
      succeed in putting the data as long as there is room in the transmit
      queue, even if transmit handshaking is in an inhibited state. In
      direct transmit mode, there is no transmit queue to buffer the output
      data during the inhibited state of transmit handshaking. Therefore,
      in direct transmit mode, an output function may not complete a
      transmission of the data if transmit handshaking changes to an
      inhibited state.

      The return value of the output functions should always be tested when
      transmit handshaking is used in direct transmit mode to ensure that all
      of the data has been transmitted. The return value can subsequently be
      used to transmit the remaining data when the transmit handshaking
      returns to an asserted state. This is demonstrated in the following
      example. In this example, it is assumed that DSR handshaking is enabled
      and the transmitter is in direct mode.

        C Example:

            void SendData(COM com, char *buf)
            {
            char *_buf = buf;

               while(*_buf != '\0')
               {
                  _buf += ComPuts(com, _buf);

                  if(*_buf != '\0')
                     while(!ComStatus(com) & DSR);   /* wait for DSR */
               }
            }

                                 2-13


      C++ Example

            void SendData(Cport& com, char *buf)
            {
            char *_buf = buf;

               while(*_buf != '\0')
               {
                  _buf += com.Put(_buf);

                  if(*_buf != '\0')
                     while(!com.Status() & DSR);   // wait for DSR
               }
            }

      Receive handshaking will always function the same regardless of the
      current mode of the transmitter.

                                 3-1


Theory of Operation
===================

   The UART
   --------
      The UART (Universal Asynchronous Receiver/Transmitter) is a single
      integrated circuit peripheral chip, which is specially designed for
      asynchronous serial communications. It is responsible for many of
      the electronic details of serial communications. The UART converts
      parallel data (bytes/characters) to and from serial signals at the
      correct baud rate, and with the assigned word length, stop bits and
      parity. It also monitors and controls the hardware status lines.
      Cport interfaces intimately with the serial port's UART.

      The name UART is a generic name used to describe a type of
      integrated circuit. serial communications in IBM and compatible
      computers is based on the National Semiconductor family of UARTs.
      These chips include:

                              INS8250
                              INS8250-B
                              INS8250A
                              INS82C50A
                              NS16450
                              NS16C450
                              NS16550A

      The latest and greatest is the NS16550A, which features transmitter
      and receiver FIFO's. If a NS16550 UART is detected by Cport when a
      serial port is opened, Cport will automatically take advantage of
      it's advanced features. These feature greatly improve performance.

   The Transmitter and Receiver
   ----------------------------
      The transmitter and receiver interact intimately with the serial
      port's UART to coordinate data exchanges between it and the transmit
      and receive queues. They also coordinate and control any enabled
      handshaking. The transmitter and receiver together constitute an
      interrupt service routine that the program will branch to any time
      the serial port's UART generates an interrupt.

      When the UART is ready for another byte/character, the transmitter
      will transfer another byte/character (if available) to the UART. In
      addition, it sends XON/XOFF characters at the request of the receiver
      when software handshaking is enabled, and monitors the status of the
      input hardware lines when hardware handshaking in enables.

      When the UART receives a new byte/character, the receiver fetches
      it from the UART and stores it in the receive queue. It also
      monitors the amount of data in the receive queue when handshaking is
      enabled, in order to perform the enabled handshaking and avoid a
      receive queue overflow. In software handshaking, requests to the
      transmitter are made to send the XON/XOFF characters. In hardware
      handshaking, the receiver manipulates the  hardware line(s) directly.

                                 3-2


   The Transmit and Receive Queues
   -------------------------------
      The receive and transmit queues provide the interface/buffering
      between the Cport input and output functions and the receiver and
      transmitter respectively. This allows the transmitter/receiver to
      operate independently from the input/output functions and vice
      versa. The transmitter is concerned only with the head of the
      transmit queue while the output functions are only concerned with
      the tail of the transmit queue. Similarly, the receiver is only
      concerned with the tail of the receive queue while the input
      functions are only concerned with the head of the receive queue.

   Input and Output Functions
   --------------------------
      Input functions retrieve data from the receive queue in the order in
      which it is placed into the receive queue by the receiver. Since the
      data is buffered, the program does not need to worry about the
      incoming data until it is ready to fetch it. The output functions
      insert data into the transmit queue and will be transmitted by the
      transmitter in the order in which the data is inserted.

   Control and Status Functions
   ----------------------------
      Control functions manipulate both the transmitter/receiver and the
      UART. The queues are independent of the control functions except
      when the queues are created and destroyed when the serial port is
      opened and close respectively. Status functions retrieve information
      from the transmitter/receiver and the UART. They also manipulate the
      UART to set status (to the remote unit).

   Direct Transmit Mode
   --------------------
      In direct transmit mode, the transmitter and transmit queue are
      removed. The output functions write directly to the UART. The output
      functions will return only after all it's data is written to the
      UART, or transmit handshaking is enabled and in an inhibited state.
      This holds up program execution but may be desirable when there are
      no other tasks to perform, since otherwise, the transmitter and
      receiver share available background time. An example of when direct
      transmit mode might be advantageous is a dedicated file transfer
      routine where the only interest is to transmit data.

                                 4-1


C Reference
===========

   Typedefs and Structures
   -----------------------

   Basic

      COM is a typedef used for storing a serial port handle.

      CPARAM is a structure type used for storing a serial port's parameters.

      byte is a typedef userd for storing a byte size value.

                                 4-2


   COM
   ------------------------------------------------------------------

   Function    Data type for storing a serial port handle.

   Syntax      #include "cport.h"
               typedef void* COM;

   Remarks     COM is a type used to store a serial port handle. The open
               functions (ComOpen and ComOpenS) return values of type COM and
               all serial port specific functions take a parameter of type COM.

   Example     Open a serial port.

                  int main(void)
                  {
                  COM com1;

                     com1 = ComOpen(COM1, B9600, W8|S1|NONE, 1024, 512);
                     if(com1 == NULL)
                     {
                        /* error */
                     }
                     ...continued

   CPARAM
   ------------------------------------------------------------------

   Function    Data type for storing a serial port's parameters.

   Syntax      #include "cport.h"
               typedef struct
               {
                  unsigned   id;
                  int        baud;
                  byte       mode;
                  unsigned   rxQ;
                  unsigned   txQ;
                  byte       htype;
                  unsigned   thresh;
               }CPARAM;

      id  -    Value that identifies the serial port. The upper 4 bits define
               the interrupt request line while the lower 12 bits define the
               port address. This technique allows for the possibility
               of custom configurations. See Table A-1 in Appendix A for a list
               of predefined values.

      baud   - Value that defines the baud rate. The actual value is the baud
               rate divisor, which allows for the possibility of custom baud
               rates. The baud rate divisor = f / (16 * baud rate) where f is
               1.8432e+6. See Table A-2 in Appendix A for a list of predefined
               baud rate divisors.

      mode   - Bit ORed value defining the word length, number of stop bits
               and the parity. See Table A-3 in Appendix A for a list of mode
               components.
                                 4-3


      * rxQ  - Size, in bytes, of the receive queue.

      * txQ  - Size in bytes, of the transmit queue.

               * Limited to 32K in small and medium memory models.

      htype  - Type of handshaking to be used. See Table A-5 in Appendix A
               for a list of handshaking components.

      thresh - Receive queue threshold.

   Remarks     CPARAM is a structure type that holds the parameters of a
               serial port. This structure is mainly used with the alternate
               open function ComOpenS and with the function ComParam.

   Example     Open COM2 at 9600 baud, 8 bits, 1 stop bit, no parity, a
               receive queue of 1024 bytes, a transmit queue of 512 bytes and
               software handshaking (XON/XOFF) with a receive queue threshold of
               3072 bytes.

               int main(void)
               {
               CPARAM param= {COM2, B9600, W8|S1|NONE, 4096, 512, SOFT, 3072};
               COM com2;

                  com2 = ComOpenS(¶m);
                  if(com2 == NULL)
                  {
                     /* error */
                  }

                  ...continued

   byte
   ------------------------------------------------------------------

   Function    Data type used for storing byte size values.

   Syntax      #include "cport.h"
               typedef unsigned character byte;

   Remarks     The byte data type is used for storing byte size values. Some
               of the Cport functions take parameters of type byte and some
               return values of type byte.

   Example     Use a byte data type for the mode parameter.

               static byte mode = W8|S1|NONE;

               byte Mode(COM terminal, byte newmode)
               {
               byte temp;

                  ComMode(terminal, newmode);
                  temp = mode;
                  mode = newmode;
                  return(temp);      /* return previous mode */
               }
                                 4-4


   Global Variables
   ----------------

   comopen_errno
   ------------------------------------------------------------------

   Function    Holds the error code from the last attempt to open a serial
               port.

   Syntax      #include "cport.h"
               extern int comopen_errno;

   Remarks     Comopen_errno holds the error code from the last attempt to
               open a serial port via a call to ComOpen or ComOpenS. If the
               last opened serial port was successfully opened, comopen_errno
               will be 0. If an error occurred while attempting to open the
               serial port the value of comopen_errno will be non-zero. See
               Table A-4 in Appendix A for a list of possible values for
               comopen_errno.

   Example     Attempt to open COM1. If an error occurs, check comopen_errno
               for the cause.

               int main(void)
               {
               COM com1;

                  com1 = ComOpen(COM1, B9600, W8|S1|NONE, 1024, 512);
                  if(com1 == NULL)
                  {
                     switch(comopen_errno)
                     {
                        case RX_ALC:
                        case TX_ALC:
                        case GEN_ALC:
                           /* memory allocation error */
                           break;

                        case NO_UART:
                           /* no UART at that address */
                           break;

                        default:
                           /* all other errors */
                           break;
                     }
                  }
                  ...continued

                                 4-5


   Control Functions
   -----------------


   Basic

      ComOpen opens a serial port using discrete parameters.

      ComOpenS opens a serial port using a structure of parameters.

      ComClose closes a currently open serial port.

      ComCloseAll closes all open serial ports.

      ComHandshake determines if and what type of handshaking scheme will be
      enabled and sets the receiver threshold.


   Intermediate

      ComParam reports on the current parameters and handshaking under which
      the specified serial port is currently operating.

      ComBaud changes the serial port's baud rate.

      ComMode changes the serial port's word length, number of stop bits and
      parity.


   Advanced

      ComRxQ resizes the receive queue.

      ComTxQ resizes the transmit queue.

      ComTx allows advanced control over the Cport transmitter.

      ComNS550 sets the receive fifo threshold of an NS16550 UART.

      ComTurbo temporarily disables/re-enables selected high priority
      interrupts that may impede high speed transfers.


                                 4-6


   ComOpen
   ------------------------------------------------------------------

   Function    Opens a serial port for communications.

   Syntax      #include "cport.h"
               COM ComOpen(unsigned id, int baud, byte mode,
                                          unsigned rxQ, unsigned txQ);
   Parameters

      id     - Value that identifies the serial port. The upper 4 bits define
               the interrupt request line, while the lower 12 bits define the
               port address. This technique allows for possibility of custom
               configurations. See Table A-1 in Appendix A for a list of
               predefined values.

      baud   - Value that defines the baud rate. The actual value is the baud
               rate divisor, which allows for the possibility of custom baud
               rates. The baud rate divisor = f / (16 * baud rate) where f is
               1.8432e+6. See Table A-2 in Appendix A for a list of predefined
               baud rate divisors.

      mode   - Bit ORed value defining the word length, number of stop bits
               and the parity. See Table A-3 in Appendix A for a list of mode
               components.

      * rxQ  - Size, in bytes, of the receive queue.

      * txQ  - Size, in bytes, of the transmit queue.

               * Limited to 32K in small and medium memory models.

   Remarks     ComOpen opens the specified serial port and returns a handle
               used to identify the newly opened serial port. If ComOpen fails
               to open the specified serial port, it returns NULL and sets
               comopen_errno to an error code. The 4 most significant bits in
               id represent the interrupt vector, while the lower 12 bits
               represent the port address. Constants are provided in cport.h
               to facilitate the formulation of the id parameter. The COMx
               values will work in most cases; however, the IRQx values can
               be ORed with the PORTx or BIOSx values to produce other
               combinations. The PORTx values are actual port addresses where
               the serial ports are normally located. The BIOSx values are
               actually macros, which fetch the port address from the BIOS data
               area. Usually the BIOSx and PORTx values will be the same, but
               it is not guaranteed. Quite often the values at BIOS2 and BIOS3
               (com 3 and com 4) will be set to 0 regardless if com3 or com4
               exist. See Table A-1 in Appendix A for a list of predefined
               values for formulating the id parameter.

               The parameter baud is the baud rate divisor that determines the
               baud rate. Achieving baud rates above 19200 is depends on many
               variables such as machine speed, cable length, handshaking
               activity, degree bidirectional transfers, number of open serial
               ports, the type UART(s) used and activity of other hardware
               interrupts.

                                 4-7


               The parameter mode determines the word length, number of stop
               bits and parity. Bits 0 and 1 determine the word length, bit 2
               determines the number of stop bits, bit 3 enables parity and
               bits 4 and 5 determine the type of parity check.

               RxQ and txQ set the size of the receive and transmit queues
               respectively. RxQ should be at least four times larger than the
               largest string or block of data the programmer intends to fetch
               from the queue at once. TxQ can be set as small as 1, but is
               not recommended. In the small and medium memory models, where
               all data is limited to 64K, the size queues are limited. In the
               compact and large memory models, each queue can be as large as
               64K-1 (65534 bytes).

   Return value   If successful, ComOpen returns a handle to the newly opened
                  serial port. In the event of an error, it returns NULL and
                  sets the global variable comopen_errno to an  error code.
                  See Table A-4 in Appendix A for a list of possible values
                  for comopen_errno.

   See also    ComOpenS, ComClose, ComCloseAll, ComBaud, ComMode, COM,
               comopen_errno

   Example     Open COM1 at 9600 baud with 8 bit words, 1 stop bit, no parity,
               a 1024 byte receiver and a 512 byte transmitter.

               int main(void)
               {
               COM com1;

                  com1 = ComOpen(COM1, B9600, W8|S1|NONE, 1024, 512);
                  if(com1 == NULL)
                  {
                     switch(comopen_errno)
                     {
                        case RX_ALC:
                        case TX_ALC:
                        case GEN_ALC:
                           /* allocation error */
                           break;

                        case NO_UART:
                           /* no UART */
                           break;

                        default:
                           /* all other errors */
                           break;
                     }
                  }
                  ...continued

                                 4-8


   ComOpenS
   ------------------------------------------------------------------

   Function    Opens a serial port for communications.

   Syntax      #include "cport.h"
               COM ComOpenS(const CPARAM *param);

   Parameters

      param  - Pointer to a type CPARAM that contains the serial port
               parameters.

   Remarks     ComOpenS is an alternative to ComOpen for opening a serial port.
               It takes a pointer to a type CPARAM. CPARAM is a structure
               that contains the serial port parameters.

   Return value   If successful, ComOpenS returns a handle to the newly opened
                  serial port. In the event of an error, it returns NULL and
                  sets the global variable comopen_errno to an error code.
                  See Table A-4 in Appendix A for a list of possible values
                  for  comopen_errno.

   See also    ComOpen, ComClose, ComCloseAll, ComParam, COM, comopen_errno

   Example     Open COM2 at 9600 baud, 8 bits, 1 stop bit, no parity, a
               receive queue of 1024 bytes, with a transmit queue of 512
               bytes and software handshaking (XON/XOFF) with a receive queue
               threshold of 3072 bytes.

               int main(void)
               {
               CPARAM param = {COM2, B9600, W8|S1|NONE, 4096, 512, SOFT, 3072};
               COM com2;

                  com2 = ComOpenS(¶m);
                  if(com2 == NULL)
                  {
                     /* error */
                  }

                  ...continued


   ComClose
   ------------------------------------------------------------------

   Function    Closes the specified serial port.

   Syntax      #include "cport.h"
               void ComClose(COM);

   Parameters

      COM    - Handle of the serial port to be closed.

                                 4-9


   Remarks     ComClose closes the specified serial port. Failing to close all
               serial ports before a program is terminated will cause the
               system to lock up.

   See also    ComCloseAll, ComOpen, ComOpenS, COM

   Example     Close the serial port prior to terminating.

               int main(void)
               {
               COM com1;

                  com1 = ComOpen(COM1, B9600, W8|S1|NONE, 1024, 512);
                  if(com1 == NULL)
                     /* error */

                  ...later

                  ComClose(com1);
                  return(0);
               }

   ComCloseAll
   ------------------------------------------------------------------

   Function    Closes all currently opened serial ports.

   Syntax      #include "cport.h"
               void ComCloseAll(void);

   Remarks     ComCloseAll closes all the currently opened serial ports.
               Failing to close all serial ports before a program is
               terminated will cause the system to lock up. ComCloseAll is
               convenient for ensuring all serial ports are closed prior to a
               program's termination.

   See also    ComClose, ComOpen, ComOpenS

   Example     Make sure all serial ports are closed prior to terminating.

               void ErrorExit(void)
               {
                  ComCloseAll();
                  exit(-1);
               }

   ComHandshake
   ------------------------------------------------------------------

   Function    Enables or disables handshaking (flow control) for the
               specified serial port.

   Syntax      #include "cport.h"
               void ComHandshake(COM, byte htype, unsigned thresh);

                                 4-10



   Parameters

      COM    - Handle of the serial port.

      htype  - Type of handshaking to be used. See Table A-5 in Appendix A
               for a list of handshaking components.

      thresh - Receive queue threshold.

   Remarks     ComHandshake enables or disables software and/or hardware
               handshaking for the specified serial port. In software
               handshaking, XON and XOFF characters are used to suspend and
               resume communications. Hardware handshaking uses any or all of
               the DTR, DSR, RTS, CTS and DCD lines to suspend and resume
               communications. Thresh determines when the receiver will
               assert or inhibit the corresponding handshaking signals. If
               no receive handshaking is specified (RTS, DTR or S_RX), the
               threshold is not used and may be set to zero.

   See also    ComParam, ComOpenS, ComTx

   Example     If COM1 is successfully opened, turn on some hardware
               handshaking and set the receiver threshold to 3/4 of the
               receiver's full size. The transmitter will not transmit unless
               both DSR and DCD are asserted. The receiver will inhibit DTR if
               the receive queue length exceeds the threshold.

               int main(void)
               {
               COM com1;

                  com1 = ComOpen(COM1, B9600, W8|S1|NONE, 1024, 512);
                  if(com1 == NULL)
                  {
                     /* error */
                  }
                  ComHandshake(com1, DSR|DTR|DCD, 768);

                  ...continued

                  ComClose(com1);
                  return(0);
               }

   ComParam
   ------------------------------------------------------------------

   Function    Retrieves the parameters of the specified serial port.

   Syntax      #include "cport.h"
               void ComParam(COM, CPARAM *param);

   Parameters

      COM    - Handle of the serial port from which to get the parameters.

                                 4-11


      param  - Pointer to a type CPARAM where the parameters will be stored.


   Remarks     ComParam retrieves the parameters and handshaking status of the
               specified serial port and stores them in a type CPARAM.

   See also    CPARAM, ComOpen, ComOpenS, ComMode, ComBaud

   Example     Open a serial port with the same configuration as one that is
               already opened.

               COM ComOpenCopy(unsigned id, COM copyme)
               {
               CPARAM param;

                  ComParam(copyme, ¶m);
                  param.id = id;
                  return(ComOpenS(¶m));
               }

   ComBaud
   ------------------------------------------------------------------

   Function    Changes the baud rate of the specified serial port.

   Syntax      #include "cport.h"
               void ComBaud(COM, int baud);

   Parameters

      COM    - Handle of the serial port.

      baud   - Value that defines the baud rate. The actual value is the baud
               rate divisor, which allows for possibility of custom baud rates.
               The baud rate divisor = f / (16 * baud rate) where f is
               1.8432e+6. See Table A-2 in Appendix A for a list of predefined
               baud rate divisors.

   Remarks     ComBaud changes the baud rate of the specified serial port. The
               parameter baud is the baud rate divisor that determines the
               baud rate.

   See also    ComOpen, ComOpenS, ComParam, ComMode

   Example     Set the specified serial port to a new baud rate.

                                 4-12


               #define NBAUD   4

               int SetBaud(COM com, unsigned n)
               {
               int baud[NBAUD] = {    B9600, B2400, B1200, B300 };

                  if(n < NBAUD)
                  {
                     ComBaud(com, baud[n]);
                     return(0);
                  }
                  else
                     return(-1);
               }


   ComMode
   ------------------------------------------------------------------

   Function    Changes the word length, number of stop bits and parity of the
               specified serial port.

   Syntax      #include "cport.h"
               void ComMode(COM, byte mode);

   Parameters

      COM    - Handle of the serial port.

      mode   - Bit ORed value defining the word length, number of stop bits
               and the parity. See Table A-3 in Appendix A for a list of mode
               components.

   Remarks     ComMode changes the word length, number of stop bits and parity
               of the specified serial port. The parameter mode determines the
               word length, number of stop bits and parity of the specified
               serial port. Bits 0 and 1 determine the word length, bit 2
               determines the number of stop bits, bit 3 enables parity and
               bits 4 and 5 determine the type of parity check.

   See also    ComOpen, ComOpenS, ComParam, ComBaud

   Example     Set the serial port to a new mode.

               #define NMODE   2

               int SetMode(COM com, unsigned n)
               {
               byte mode[NMODE] = { W8|S1|NONE, W7|S1|EVEN };

                  if(n < NMODE)
                  {
                     ComMode(com, mode[n]);
                     return(0);
                  }
                  return(-1);
               }
                                 4-13



   ComRxQ
   ------------------------------------------------------------------

   Function    Resizes the specified serial port's receive queue.

   Syntax      #include "cport.h"
               unsigned ComRxQ(COM, unsigned size);

   Parameters

      COM    - Handle of the serial port.

      size   - New receive queue size.


   Remarks     ComRxQ resizes the specified serial port's receive queue. The
               memory currently allocated for the receive queue is freed, and
               new memory is allocated. If ComRxQ is unable to allocate the
               specified amount memory, it will try to reallocate memory for
               the previous size. ComRxQ returns the new queue size. If
               memory was successfully allocated for the new size, the return
               value will be size. If the previous size is reallocated, the
               return value will be the previous size. If no memory could be
               allocated, ComRxQ returns zero.

               No data can be received while the new receive queue is being
               resized. However, data in the transmit queue will continue to
               be transmitted normally.

   Return value   ComRxQ returns the new receive queue size.

   See also    ComTxQ, ComOpen, ComOpenS

   Example     Enlarge the receive queue for a file transfer.

               #define LARGE_RX   4096
               int ReceiveFile(COM com, const char *filename)
               {
               CPARAM param;

                  ComParam(com, ¶m);
                  if(ComRxQ(com, LARGE_RX) != LARGE_RX)
                     return(-1);

                     ... transfer file here

                     /* Restore original size   */
                  if(ComRxQ(com, param.rxQ) != param.rxQ)
                     return(-2);
                  else
                     return(0);
               }

                                 4-14


   ComTxQ
   ------------------------------------------------------------------

   Function    Resizes the specified serial port's transmit queue.

   Syntax      #include "cport.h"
               unsigned ComTxQ(COM, unsigned size);

   Parameters

      COM    - Handle of the serial port.

      size   - New transmit queue size.

   Remarks     ComTxQ resizes the specified serial port's transmit queue. The
               memory currently allocated for the transmit queue is freed, and
               new memory is allocated. If ComTxQ is unable to allocate the
               specified amount memory, it will try to reallocate memory for
               the previous size. ComTxQ returns the new queue size. If memory
               was successfully allocated for the new size, the return value
               will be size. If the previous size is reallocated, the return
               value will be the previous size. If no memory could be
               allocated, ComTxQ returns zero.

               No data can be transmitted while the new transmit queue is
               being resized. However, data to the receive queue will
               continue to be received normally.

   Return value   ComTxQ returns the new transmit queue size.

   See also    ComRxQ, ComOpen, ComOpenS

   Example     Enlarge the transmit queue for a file transfer.

               #define LARGE_TX   4096
               int TransmitFile(COM com, const char *filename)
               {
               CPARAM param;

                  ComParam(com, ¶m);
                  if(ComTxQ(com, LARGE_TX) != LARGE_TX)
                     return(-1);

                     ... transfer file here

                     /* Restore original size   */
                  if(ComTxQ(com, param.txQ) != param.txQ)
                     return(-2);
                  else
                     return(0);
               }

                                 4-15


   ComTx
   ------------------------------------------------------------------

   Function    Transmitter control.

   Syntax      #include "cport.h"
               int ComTx(COM, int cmnd);

   Parameters

      COM    - Handle of the serial port.

      cmnd   - Determines the action to be taken on the transmitter See Table
               A-9 in Appendix A for a list of transmitter options.

   Remarks     ComTx  allows advanced control of the Cport transmitter The
               transmitter can be turned on and off to suspend and resume
               transmissions. This function can be very useful when
               implementing your own handshaking scheme. In addition, it can
               inform the output functions to transmit directly when the
               transmitter is turned off.

   Return value   ComTx returns the previous status of the transmitter

   See also    ComHandshake, ComOpenS, ComParam

   Example     Put a priority character directly  to the  serial port.

               void PriorityPutc(COM com, char c)
               {
               int tx;

                  tx = ComTx(com, TX_DIRECT | OFF);
                  ComPutc(com, c);
                  ComTx(com, tx);   /* restore original state */
               }


   ComNS550
   ------------------------------------------------------------------

   Function    NS16550 UART setup.

   Syntax      #include "cport.h"
               void ComNS550(COM, int trigger);

   Parameters

      COM    - Handle of the serial port.
   trigger   - Trigger threshold for the UART receive fifo. See Table A-12 in
               Appendix A for a list of trigger thresholds.

   Remarks     If Cport detects an NS16550 UART when a serial port is opened,
               Cport automatically takes advantage of it's advanced
               capabilities.

                                 4-16


               The receive fifo threshold is the number of bytes in the
               receive fifo that will cause an interrupt to be generated. By
               default, the receive fifo threshold is set  to 14 bytes.
               ComNS550 allows this receive fifo trigger threshold to be
               changed.

   See Also    ComUart
   Example     If the specified serial port is an NS16550 set the trigger
               level to 1 byte.

               void SetThreshIf550(COM com)
               {
                  if(ComUart(com) == NS16550)
                     ComNS550(com, T550_1);
               }

   ComTurbo
   ------------------------------------------------------------------

   Function    Disables/re-enables high priority interrupts.

   Syntax      #include "cport.h"
               void ComTurbo(int options);

   Parameters

      options - Bit mask of options. See Table A-6 in Appendix A for possible
               options.

   Remarks     During high speed data exchanges, certain events that cause
               high priority interrupts can inhibit serial communications and
               possibly cause (over run) errors. This is especially true of
               the timer, which periodically uses extra time and the
               keyboard, if keys are pressed.

               ComTurbo disables selected high priority interrupts or
               restores all of them. The high priority interrupts should
               never be disabled permanently or for long periods of time. The
               timer interrupt is not actually disabled but diverted,
               allowing the system clock to continue to update. All other
               options are actually disabled when specified.

   Example     Disable the keyboard and divert the timer while a block is
               transferred at high speed.

               #include <time.h>
               #define BLK_SZ 128

                                 4-17


               int GetBlock(COM com, byte* block, clock_t timeout)
               {
               int rv;

                     /* assume 115200 baud
                     */
                  ComTurbo(TIMER | KEYBOARD);
                  timeout += clock();
                  while(ComLenRx(com) < BLK_SZ)
                  {
                     if(clock() > timeout)
                     {
                        ComTurbo(OFF);
                        return(0);
                     }
                  }
                  rv = ComIn(com, block, BLK_SZ);
                  ComTurbo(OFF);
                  return(rv);
               }
                                 4-18


   Input Functions
   ---------------


   Basic

      ComGetc gets a character from the receive queue.

      ComGets gets a string of characters from the receive.

      ComIn gets a block of data from the receive queue.

      ComFlushRx flushes the receive queue and receiver.

      ComLenRx calculates the number of characters/bytes in the receive queue.


   Intermediate

      ComPeek returns a copy of the head character/byte without removing it
      from the receive queue.

      ComRxScan scans the receive queue for a specified character.

                                 4-19


   ComGetc
   ------------------------------------------------------------------

   Function    Fetches a character from the specified serial port's receive
               queue.
   Syntax      #include "cport.h"
               char ComGetc(COM);

   Remarks     ComGetc fetches the head character from the specified serial
               port's receive queue. If there are no characters in the
               receive queue, ComGetc returns a NULL character ('\0').

   Parameters

      COM    - Handle of the serial port.

   Return value   If successful, ComGetc returns the character from the receive
                  queue. If it fails, it returns a NULL character ('\0').

   See also    ComPutc, ComGets, ComIn, ComPeek

   Example     Get a character from the modem and test if it is a start of
               header control character.

               #define SOH 1
               int CheckForSOH(COM modem)
               {
               char c;

                  c = ComGetc(modem);
                  return(c == SOH);
               }


   ComGets
   ------------------------------------------------------------------
   Function    Fetches a string of characters from the specified serial
               port's receive queue.

   Syntax      #include "cport.h"
               char *ComGets(COM, char *str, int maxc, char termc);

   Parameters

      COM    - Handle of the serial port.
      str    - Pointer to the buffer where the string of characters will be
               stored.

      maxc   - Maximum number of characters to fetch.

      termc  - Termination character. ComGets will return if this character
               is encountered.

   Remarks     ComGets fetches a string of characters from the specified
               serial port's receive queue. The string will be stored in str.
               Str must be at least maxc + 1 characters long to allow for the

                                 4-20


               NULL terminator. ComGets will return on the first occurrence
               of one of three conditions: 1) the character termc is
               encountered; 2) maxc characters are reached; or 3) no more
               characters are available in the receive queue.

   Return value   ComGets returns a pointer to the NULL terminated string.

   See also    ComPuts, ComGetc, ComIn, ComLenRx

   Example     Get a measurement from the specified instrument if one is
               ready.

               #define MEAS_SIZ   24
               char* GetMeasurment(COM instrument, char* buf)
               {
                  if(ComLenRx(instrument) > MEAS_SIZ)
                     return(ComGets(instrument, buf, MEAS_SIZ, '\n'));

                  else
                     return(NULL);
               }


   ComIn
   ------------------------------------------------------------------

   Function    Fetches a block of bytes from the specified serial port's
               receive queue.

   Syntax      #include "cport.h"
               unsigned ComIn(COM, void *abyte, unsigned nbyte);

   Parameters

      COM    - Handle of the serial port.

      abyte  - Pointer to a buffer where the block of bytes will be stored.

      nbyte  - Number of bytes to get from the receive queue.

   Remarks     ComIn fetches a block of bytes from the specified serial
               port's the receive queue and stores it in abyte. ComIn will
               always fetch num_byte bytes unless not enough bytes are
               available. ComIn is well suited for receiving binary data.

   Return value   ComIn returns the number of bytes actually fetched.

   See also    ComOut, ComGetc, ComGets, ComLenRx

                                 4-21


   Example     Get a block of 1024 bytes from the serial port.

               #include <time.h>
               #define BLK_SZ    1024
               #define TIMEOUT   -1

               int GetBlock(COM datalink, byte* buf, clock_t timeout)
               {

                  timeout += clock();
                  while(ComLenRx(datalink) < BLK_SZ)
                  {
                     if(clock() > timeout)
                        return(TIMEOUT);
                  }
                  return(ComIn(datalink, buf, BLK_SZ));
               }


   ComFlushRx
   ------------------------------------------------------------------

   Function    Flushes the specified serial port's receiver and receive
               queue.

   Syntax      #include "cport.h"
               void ComFlushRx(COM);

   Parameters

      COM    - Handle of the serial port.

   Remarks     ComFlushRx deletes the specified serial port's receive queue
               and the UART of any existing characters/bytes.

   See also    ComLenRx, ComFlushTx

   Example     If a receive flush command is in order, flush the receiver.

               void RemoteCommand(COM com, int command)
               {
                  switch(command)
                  {
                     case TX_FLUSH:
                        ComFlushTx(com);
                        break;

                     case RX_FLUSH:
                        ComFlushRx(com);
                        break;

                     ...continued
                  }
               }
                                 4-22


   ComLenRx
   ------------------------------------------------------------------

   Function    Calculates the number of characters/bytes in the specified
               serial port's receive queue.

   Syntax      #include "cport.h"
               unsigned ComLenRx(COM);

   Parameters

      COM    - Handle of the serial port.

   Remarks     ComLenRx calculates the number of characters/bytes in the
               specified serial port's receive queue.

   Return value   ComLenRx returns the number of characters/bytes residing
                  in the receive queue.

   See also    ComFlushRx, ComLenTx

   Example     Get a measurement from the specified instrument if one is
               ready.

               #define MEAS_SIZ   24
               char* GetMeasurment(COM instrument, char* buf)
               {
                  if(ComLenRx(instrument) > MEAS_SIZ)
                  {
                     ComGets(instrument, buf, MEAS_SIZ, '\n');
                     return(buf);
                  }
                  else
                     return(NULL);
               }


   ComPeek
   ------------------------------------------------------------------

   Function    Fetches a copy of the head character from the specified
               serial port's receive queue.

   Syntax      #include "cport.h"
               char ComPeek(COM);

   Parameters

      COM    - Handle of the serial port.

   Remarks     ComPeek fetches a copy of the head character from the
               specified serial port's receive queue. ComPeek will not
               remove the character from the queue.

   Return value   ComPeek returns the copy of the head character.

                                 4-23


   See also    ComGetc, ComRxScan


   Example     Get the head character, if it is a control character.

               #include <ctype.h>
               char GetIfControl(COM com)
               {
               char peek;

                  peek = ComPeek(com);

                  if(iscntrl(peek))
                     return(ComGetc(com));

                  else
                     return('\0');
               }


   ComRxScan
   ------------------------------------------------------------------

   Function    Scans the receive queue of the specified serial port for a
               specific character.

   Syntax      #include "cport.h"
               unsigned ComRxScan(COM, char c);

   Parameters

      COM    - Handle of the serial port.

      c      - Character to scan for.

   Remarks     ComRxScan searches for the character c in the specified serial
               port's receive queue. If the character is not found, ComRxScan
               returns a zero. Otherwise it returns the offset into the
               receive queue of the first occurrence of c starting at 1 for
               the first character. This is the number of characters that
               must be fetched to get all data up to and including the
               character scanned for.

   Return value   ComRxScan returns the offset into the receive queue to the
                  first occurrence of c. If c does not exist, ComRxScan
                  returns a zero.

   See also    ComPeek

                                 4-24


   Example     Get the next line terminated with a '\n'.

               char *GetLine(COM com, char *buffer)
               {
               int n;

                  n = ComRxScan(com, '\n');
                  if(n > 0 && n < 80)
                     return(ComGets(com, buffer, n, '\n'));
                  else
                     return(NULL);
               }

   Example     Get the next message terminated with a EOT control character.

               #define EOT   0x4

               int GetMessage(COM com, byte *buffer)
               {
               int n;

                  n = ComRxScan(com, EOT);
                  if(n > 0 && n < 80)
                     return(ComIn(com, buffer, n));
                  else
                     return(0);
               }

                                 4-25


   Output Functions
   ----------------


   Basic

      ComPutc puts a character to the transmit queue.

      ComPuts puts a string of characters to the transmit queue.

      ComOut puts a block of data to the transmit queue.

      ComFlushTx flushes the transmit queue and transmitter.

      ComLenTx calculates the number of characters in the transmit queue.


   Advanced

      ComTxWait pauses program execution until the transmitter has emptied.

                                 4-26


   ComPutc
   ------------------------------------------------------------------

   Function    Puts a character into the specified serial port's transmit
               queue.

   Syntax      #include "cport.h"
               int ComPutc(COM, char c);

   Parameters

      COM    - Handle of the serial port.

      c      - Character to be put into the transmit queue.

   Remarks     ComPutc puts a character into the specified serial port's
               transmit queue to be transmitted. If the transmit queue is
               full, the character is not put and ComPutc returns a 0.

   Return value   On success, ComPutc returns a 1. If it fails, it returns 0.

   See also    ComGetc, ComPuts, ComOut

   Example     Echo the keyboard to the serial port when fetching a keystroke.

               #include <conio.h>

               static COM echo;

               char GetKey(void)
               {
               char c;

                  if(kbhit())
                  {
                     c = getch();
                     ComPutc(echo, c);
                     return(c);
                  }
                  else
                     return('\0');
               }


   ComPuts
   ------------------------------------------------------------------

   Function    Puts a string of characters into the specified serial port's
               transmit queue.

   Syntax      #include "cport.h"
               int ComPuts(COM, const char *str);

                                 4-27


   Parameters

      COM    - Handle of the serial port.

      str    - Pointer to the string to be put into the transmit queue.

   Remarks     ComPuts puts the string str into the specified serial port's
               transmit queue to be transmitted. If the transmit queue
               becomes full, ComPuts will not attempt to put any more
               characters in the queue.

   Return value   ComPuts returns the actual number of characters put into
                  the transmit queue.

   See also    ComGets, ComPutc, ComOut

   Example   Dial a number on the modem.

               #include <string.h>

               void ModDial(COM modem, const char* number)
               {
               char dial[24] = "ATDT";

                  strcat(dial, number);
                  strcat(dial, "\r");
                  ComPuts(modem, dial);
               }


   ComOut
   ------------------------------------------------------------------

   Function    Puts a block of bytes into the specified serial port's
               transmit queue.

   Syntax      #include "cport.h"
               unsigned ComOut(COM, const void *abyte, unsigned nbyte);

   Parameters

      COM    - Handle of the serial port.

      abyte  - Pointer to the block of data to be put  into the transmit
               queue.

      nbyte  - Number of bytes to be put into the transmit  queue.

   Remarks     ComOut puts the block of bytes pointed to by abyte into the
               specified serial port's transmit queue to be transmitted.

   Return value   ComOut returns the number of bytes actually put into the
                  transmit queue.

   See also    ComIn, ComPutc, ComPuts

                                 4-28


   Example     Send a block of 128 bytes to the transmitter.

               #define BLK_SZ 128
               int SendBlock(COM com, const byte* block)
               {
               int rv;

                  rv = ComOut(com, block, BLK_SZ);
                  if(rv < BLK_SZ)
                     return(-1);

                  else
                     return(0);
               }


   ComFlushTx
   ------------------------------------------------------------------

   Function    Flushes the specified serial port's transmit queue.
   Syntax      #include "cport.h"
               void ComFlushTx(COM);

   Parameters

      COM    - Handle of the serial port.

   Remarks     ComFlushTx deletes any existing characters in the specified
               serial port's transmit queue.

   See also    ComFlushRx, ComLenTx

   Example     If a transmit flush command is in order, flush the transmit
               queue.

               void RemoteCommand(COM com, int command)
               {
                  switch(command)
                  {
                     case TX_FLUSH:
                        ComFlushTx(com);
                        break;

                     case RX_FLUSH:
                        ComFlushRx(com);
                        break;

                     ...continued
                  }
               }

                                 4-29


   ComLenTx
   ------------------------------------------------------------------

   Function    Calculates the number of characters/bytes in the specified
               serial port's transmit queue.

   Syntax      #include "cport.h"
               unsigned ComLenTx(COM);

   Parameters

      COM    - Handle of the serial port.

   Remarks     ComLenTx calculates the number of characters/bytes in the
               specified serial port's transmit queue.

   Return value   ComLenTx returns the number of characters/bytes in the
                  transmit queue.

   See also    ComLenRx, ComFlushTx

   Example     Check if the transmitter has reached 3/4 of its capacity.

               #define TX_SIZE      1024

               int IsAboveThresh(COM sprinter)
               {
                  return(ComLenTx(sprinter) > (TX_SIZE * 3 / 4));
               }


   ComTxWait
   ------------------------------------------------------------------

   Function    Waits for the specified serial port's transmitter to empty

   Syntax      #include "cport.h"
               void ComTxWait(COM);

   Parameters

      COM    - Handle of the serial port.

   Remarks     When a transmit queue becomes empty, the UART may not have
               actually transmitted the last of the bytes. A program may need
               to know when all the data has actually been transmitted so
               that it may, for example, change the state of the hardware
               lines during half duplex communications. ComTxWait will return
               after the UART has been emptied of data.

   See Also    ComLenTx

                                 4-30


   Example     Send a string to a half duplex device. This examples assumes
               that the device is monitoring our RTS line to determine a
               transmit or receive state.

               void SendMessage(COM device, const char* msg)
               {
                  ComRts(device, ON);
                  ComPuts(device, msg);
                  while(ComLenTx(device));
                  ComTxWait(device);
                  ComRts(device, OFF);
               }
                                 4-31


   Status Functions
   ----------------


   Basic

      ComError detects hardware and software errors.


   Intermediate

      ComStatus returns the status of the software and input hardware lines.

      ComRts controls the RTS output line.

      ComDtr controls the DTR output line.


   Advanced

      ComOut1 controls the general purpose OUT1 output line.

      ComUart determines what type of UART chip is residing at a serial port.

                                 4-32


   ComError
   ------------------------------------------------------------------

   Function    Determines if any errors have occurred on the specified
               serial port since the last call to ComError.

   Syntax      #include "cport.h"
               unsigned ComError(COM);

   Parameters

      COM    - Handle of the serial port.

   Remarks     ComError determines if any errors are pending on the specified
               serial port. After a call to ComError, the errors are cleared.
               ComError returns a bit ORed error word. See Table A-7 in
               Appendix A for a list of bit definitions.

   Return value   If an error has occurred, ComError returns an error word.
                  If no errors have occurred, it returns a 0.

   See also    ComStatus

   Example     Determine the source of the error if one has occurred.

               #define HARDWARE   (PARITY | FRAMING | BREAK | RX_FIFO)

               void CheckForErrors(COM dvm)
               {
               unsigned err;

                  if((err = ComError(dvm)) == 0)
                     return;

                  else if(err & OVERUN)
                  {
                     /* over run error */
                  }
                  else if(err & HARDWARE)
                  {
                     /* hardware errors */
                  }
                  else if(err & (TXFULL | RXFULL))
                  {
                     /* queue errors */
                  }
               }

                                 4-33


   ComStatus
   ------------------------------------------------------------------

   Function    Retrieves the status of the specified serial port's software
               and hardware lines.

   Syntax      #include "cport.h"
               unsigned ComStatus(COM);

   Parameters

      COM    - Handle of the serial port.

   Remarks     ComStatus retrieves the status of the specified serial port's
               software and hardware lines. ComStatus returns a bit ORed
               status word. See Table A-8 in Appendix A for a list of bit
               definitions.

   Return value   ComStatus returns the status word of the software and
                  hardware lines.

   See also    ComError, ComRts, ComDtr

   Example     Test if the modem is powered up and ready.

               #include <dos.h>

               int CheckModem(COM modem)
               {
                  ComDtr(modem, ON);
                  delay(40);

                  return((ComStatus(modem) & DSR) != 0);
               }


   ComRts
   ------------------------------------------------------------------

   Function    Asserts or inhibits the specified serial port's Request to
               Send line.

   Syntax      #include "cport.h"
               void ComRts(COM, byte on_off);

   Parameters

      COM    - Handle of the serial port.

      on_off - Determines whether RTS is to be asserted or inhibited. See
               Table A-10 in Appendix A.

   Remarks     ComRts asserts or inhibits the specified serial port's RTS
               line depending on the value of on_off. If the value of on_off
               is ON, RTS is asserted. If the value of on_off is OFF, RTS is
               inhibited. In many cases, this signal will be looked at by the

                                 4-34


               remote device to determine if it is safe to transmit. This
               gives the programmer the ability to turn off the remote
               device's transmitter.

               NOTE: ComRts should never be called when RTS hardware
               handshaking is enabled.

   See also    ComDtr, ComStatus, ComHandshake

   Example     Put the device in an on or off line state. (Assumes the
               remote device will not send data without our RTS asserted)

               void OffLine(COM device)
               {
                  ComRts(device, OFF);
               }
               void OnLine(COM device)
               {
                  ComRts(device, ON);
               }


   ComDtr
   ------------------------------------------------------------------

   Function    Asserts or inhibits the specified serial port's  Data
               Terminal Ready line.

   Syntax      #include "cport.h"
               void ComDtr(COM, byte on_off);

   Parameters

      COM    - Handle of the serial port.

      on_off - Determines whether DTR is to be asserted or inhibited. See
               Table A-10 in Appendix A.

   Remarks     ComDtr asserts or inhibits the specified serial port's DTR
               line depending on the value of on_off. If the value of on_off
               is ON, DTR is asserted. If the value of on_off is OFF, DTR is
               inhibited. In many cases, this signal will be looked at by the
               remote device to determine if it is safe to transmit. This
               gives the programmer the ability to turn off the remote
               device's transmitter.

               NOTE: ComDtr should never be called when DTR hardware
               handshaking is enabled.

   See also    ComRts, ComStatus, ComHandshake

                                 4-35


   Example     Put the device in an on or off line state. (Assumes the remote
               device will not send data without our DTR asserted).

               void OffLine(COM device)
               {
                  ComDtr(device, OFF);
               }
               void OnLine(COM device)
               {
                  ComDtr(device, ON);
               }


   ComOut1
   ------------------------------------------------------------------

   Function    Asserts or inhibits the specified serial port's Out1 line.

   Syntax      #include "cport.h"
               void ComOut1(COM, byte on_off);

   Parameters

      COM    - Handle of the serial port.

      on_off - Determines whether OUT1 is to be asserted or inhibited. See
               Table A-10 in Appendix A.

   Remarks     ComOut1 asserts or inhibits the specified serial port's general
               purpose OUT1 line depending on the value of on_off. If the
               value of on_off is ON, OUT1 is asserted. If the value of
               on_off is OFF, OUT1 is inhibited. OUT1 is a general purpose
               output sometimes utilized by a device for a special feature
               or reset.

   See also    ComRts, ComDtr

   Example     Reset a smart modem.

               void SmartReset(COM modem)
               {
                  ComOut1(modem, ON);
                  delay(50);
                  ComOut1(modem, OFF);
               }


   ComUart
   ------------------------------------------------------------------

   Function    Determines the type of UART at the specified serial port.

   Syntax      #include "cport.h"
               int ComUart(COM);

                                 4-36


   Parameters

      COM    - Handle of the serial port.

   Remarks     ComUart determines the type of UART chip that resides at the
               specified serial port. See Table A-11 in Appendix A for a list
               of UART types.

   Return value   ComUart returns a value representative of the type of UART
                  that was detected.

   See Also    ComNS550


   Example     If the specified serial port has an NS16550 UART, set the
               trigger level to 1 byte.

               void SetThreshIf550(COM com)
               {
                  if(ComUart(com) == NS16550)
                     ComNS550(com, T550_1);
               }
                                 4-37


   Data Integrity
   --------------


   Intermediate

      ComChecksum calculates a byte checksum of a block of data.

      ComCrc16 calculates a 16 bit cyclic redundancy check (CRC) on a block
      of data.

      ComCrc32 calculates a 32 bit cyclic redundancy check (CRC) on a block
      of data.

                                 4-38


   ComChecksum
   ------------------------------------------------------------------

   Function    Performs a byte checksum calculation on a block of data.

   Syntax      #include "cport.h"
               byte ComChecksum(const void *abyte, unsigned nbyte);

   Parameters

      abyte  - Pointer to the block on which the checksum is to be performed.

      nbyte  - Number of bytes in the block.

   Remarks     ComChecksum performs a byte checksum on the block of bytes
               pointed to by abyte. The checksum is calculated by summing all
               the bytes in the block.

   Return value   ComChecksum returns a one byte checksum.

   See also    ComCrc16, ComCrc32, ComIn, ComOut

   Example     Verify that the actual checksum matches the received checksum.

               struct Xblock{
                  byte num;
                  byte _num;
                  byte data[128];
                  byte checksum;
               }block;

               int GetXblock(COM com, Xblock *block)
               {
                  ComIn(com, block, sizeof(Xblock));

                  if((ComChecksum(block->data, 128) - block->checksum) != 0)
                     return(-1);
                  else
                     return(0);
               }


   ComCrc16
   ------------------------------------------------------------------

   Function    Performs a 16 bit cyclic redundancy check on a block of data.

   Syntax      #include "cport.h"
               unsigned ComCrc16(const void *abyte, unsigned nbyte);

   Parameters

      abyte  - Pointer to the block on which the 16 bit cyclic redundancy
               check is to be performed.

      nbyte  - Number of bytes in the block.

                                 4-39


   Remarks     ComCrc16 performs a 16 bit cyclic redundancy check on the
               block of data pointed to by abyte.

   Return value   ComCrc16 returns the 16 bit CRC value.

   See also    ComCrc32, ComChecksum, ComIn, ComOut

   Example     Verify that the actual CRC matches the received CRC.

               struct Xblock{
                  byte num;
                  byte _num;
                  byte data[128];
                  unsigned crc;
                  }block;

               int GetXblock(COM com, Xblock *block)
               {
                  ComIn(com, block, sizeof(Xblock));

                     /* Check the calculated CRC against the block's CRC.
                     */
                  if(ComCrc16(block->data, 128) != block->crc)
                     return(-1);
                  else
                     return(0);
               }


   ComCrc32
   ------------------------------------------------------------------

   Function    Performs a 32 bit cyclic redundancy check on a block of data.

   Syntax      #include "cport.h"
               unsigned long ComCrc32(const void *abyte, unsigned nbyte);

   Parameters

      abyte  - Pointer to the block on which the 32 bit cyclic redundancy
               check is to be performed.

      nbyte  - Number of bytes in the block.

   Remarks     ComCrc32 performs a 32 bit cyclic redundancy check on the
               block of data pointed to by abyte.

   Return value   ComCrc32 returns the 32 bit CRC value.

   See also    ComCrc16, ComChecksum, ComIn, ComOut

                                 4-40


   Example     Verify that the actual CRC matches the received CRC.

               struct Packet
               {
                  byte num;
                  byte data[1024];
                  unsigned long crc;
                  }packet;

               int GetBlock(COM com, Packet* packet)
               {
                  ComIn(com, packet, sizeof(Packet));

                     /* Check the calculated CRC against the packet's CRC.
                     */
                  if(ComCrc32(packet->data, 1024) != packet->crc)
                     return(-1);
                  else
                     return(0);
               }
                                 4-41


   Misc Functions
   --------------


   Advanced

      ComSetBreak sets a break condition.

      ComClrBreak clears a break condition.

      ComPutScrtch writes to the UART's scratch register.

      ComGetScrtch reads the UART's scratch register.

                                 4-42


   ComSetBreak
   ------------------------------------------------------------------

   Function    Set a break condition on the specified serial port.

   Syntax      #include "cport.h"
               void ComSetBreak(COM);

   Parameters

      COM  - Handle of the serial port.

   Remarks     ComSetBreak sets a break condition on the specified serial
               port. The break condition will stay in effect until a
               subsequent call to ComClrBreak is made.

   See also    ComClrBreak

   Example     If the an abort condition has been declared, set a break
               condition. When it clears, release the break condition.

               void Abort(COM com, int abrt)
               {
               static int brkflg;

                  if(abrt && !brkflg)
                     ComSetBreak(com);

                  else if(!abrt && brkflg)
                     ComClrBreak(com);
               }


   ComClrBreak
   ------------------------------------------------------------------

   Function    Clears a previously set break condition on the specified
               serial port.

   Syntax      #include "cport.h"
               void ComClrBreak(COM);

   Parameters

      COM    - Handle of the serial port.

   Remarks     ComClrBreak clears a previously set break condition on the
               specified serial port.

   See also    ComSetBreak
                                 4-43


   Example     If the an abort condition has been declared, set a break
               condition. When it clears, release the break condition.

               void Abort(COM com, int abrt)
               {
               static int brkflg;

                  if(abrt && !brkflg)
                     ComSetBreak(com);

                  else if(!abrt && brkflg)
                     ComClrBreak(com);
               }


   ComPutScrtch
   ------------------------------------------------------------------

   Function    Writes a byte to the specified serial port's scratch register.

   Syntax      #include "cport.h"
               void ComPutScrtch(COM, byte abyte);

   Parameters

      COM    - Handle of the serial port.

      abyte  - The byte to be written to the scratch register.

   Remarks     ComPutScrtch writes the byte value abyte to the specified
               serial port's UART scratch register. Not all UARTs have a
               scratch register.

   See also    ComGetScrtch

   Example     Exchange a value with the scratch register.

               byte ScratchExchange(COM com, byte value)
               {
               byte rv;

                  rv = ComGetScrtch(com);   /* read the scratch register */
                  ComPutScrtch(com, value);   /* write to the scratch register */
                  return(rv);
               }


   ComGetScrtch
   ------------------------------------------------------------------

   Function    Fetches the byte stored in the specified serial port's scratch
               register.

   Syntax      #include "cport.h"
               byte ComGetScrtch(COM);

                                 4-44


   Parameters

      COM    - Handle of the serial port.

   Remarks     ComGetScratch reads the byte in the specified serial port's
               UART scratch register. Not all UARTs have a scratch register.

   Return value   ComGetScrtch returns the byte read from the UART scratch
                  register.

   See also    ComPutScrtch

   Example     Exchange a value with the scratch register.

               byte ScratchExchange(COM com, byte value)
               {
               byte rv;

                  rv = ComGetScrtch(com);   /* read the scratch register */
                  ComPutScrtch(com, value);   /* write to the scratch register */
                  return(rv);
               }

                                 5-1


C++ Reference
=============

   Control Functions
   -----------------


   Basic

      Cport::Cport constructs serial port instance with either discrete
      parameters or a structure of parameters.

      Cport::operator int returns the results of constructing a serial port
      instance.

      Cport::Handshake determines if and what type of handshaking scheme
      will be enabled and sets the receive queue threshold.


   Intermediate

      Cport::Param reports on the current parameters and handshaking under
      which a serial port is currently operating.

      Cport::Baud changes the baud rate.

      Cport::Mode changes the word length, number of stop bits and parity.


   Advanced

      Cport::RxQ resizes the receive queue.

      Cport::TxQ resizes the transmit queue.

      Cport::Tx allows advanced control over the  transmitter.

      Cport::NS550 sets the receive fifo threshold of an NS16550 UART.

      Cport::Turbo temporarily disables/re-enables selected high priority
      interrupts that may impede high speed communications.

                                 5-2


   Cport::Cport
   ------------------------------------------------------------------

   Function    Constructor.

   Syntax      #include "cport.h"
               Cport::Cport(unsigned id, int baud, byte mode = W8|S1|NONE,
                  unsigned rxQ = 1024, unsigned txQ = 512, byte htype = OFF);
               or

               Cport::Cport(unsigned id, int baud, byte mode, unsigned rxQ,
                                 unsigned txQ, byte htype, unsigned thresh);
               or

               Cport::Cport(const CPARAM& param)

   Parameters

      id     - Value that identifies the serial port. The upper 4 bits define
               the interrupt request line, while the lower 12 bits define the
               port address. This technique allows for possibility of custom
               configurations. See Table A-1 in Appendix A for a list of
               predefined values.

      baud   - Value that defines the baud rate. The actual value is the
               baud rate divisor, which allows for the possibility of custom
               baud rates. The baud rate divisor = f / (16 * baud rate) where
               f is 1.8432e+6. See Table A-2 in Appendix A for a list of
               predefined baud rate divisors.

      mode   - Bit ORed value defining the word length, number of stop bits
               and the parity. See Table A-3 in Appendix A for a list of mode
               components.

      * rxQ  - Size, in bytes, of the receive queue.

      * txQ  - Size, in bytes, of the transmit queue.

               * Limited to 32K in small and medium memory models.

      htype  - Type of handshaking to be used. See Table A-5 in Appendix A
               for a list of handshaking components.

      thresh - Receive queue threshold.

   Remarks     The constructor creates an instance of the specified serial
               port. If the constructor is unable to open the specified
               serial port, the instance of the serial port will return an
               error code when casted to an integer. If the port is
               successfully opened, the instance will return a zero when
               casted to an integer.

               The 4 most significant bits in id represent the interrupt
               vector. The lower 12 bits represent the port address.
               Constants are provided to facilitate the formulation of the id
               parameter. The COMx values will work in most cases, however,

                                 5-3


               the IRQx values can be ORed with the PORTx or BIOSx values to
               produce other combinations. The PORTx values are actual port
               addresses where the serial ports are normally located. The
               BIOSx values are actually macros, which fetch the port address
               from the BIOS data area.

               The parameter baud is the baud rate divisor, that determines
               the baud rate. Achieving baud rates above 19200 is largely
               dependent on many variables, such as machine speed, cable
               length, handshaking activity, degree bidirectional transfers,
               number of open serial ports, the type UART(s) used and
               activity of other hardware interrupts.

               The parameter mode determines the word length, number of stop
               bits and parity. Bits 0 and 1 determine the word length, bit 2
               determines the number of stop bits, bit 3 enables parity and
               bits 4 and 5 determine the type of parity check.

               RxQ and txQ set the size of the receive and transmit queues
               respectively. RxQ should be at least 4 times larger than the
               largest string or block of data expected. TxQ can be set as
               small as 1, but it is not recommended. In the small and medium
               memory models where all data is limited to 64K, the size of
               the queues are limited. In the compact and large memory
               models, each queue can be as large as 64K -1 (65534 bytes).

   See Also    Cport::operator int

   Example     Open COM1 at 9600 baud with 8 bit words, 1 stop bit, no
               parity, a 1024 byte receiver and a 512 byte transmitter.

               int main(void)
               {

                  Cport com1(COM1, B9600, W8|S1|NONE, 1024, 512);
                  if((int)com1 != NO_ERR)
                  {
                     switch(com1)
                     {
                        case RX_ALC:
                        case TX_ALC:
                        case GEN_ALC:
                           // allocation error
                           break;

                        case NO_UART:
                           // no UART
                           break;

                        default:
                           // all other errors
                           break;
                     }
                  }
                  ...continued

                                 5-4


   Cport::operator int
   ------------------------------------------------------------------

   Function    Gets the error code from when the instance of the serial port
               was constructed.

   Syntax      #include "cport.h"
               Cport::operator int()

   Remarks     When an instance of a serial port is constructed, the
               specified serial port is not necessarily successfully opened.
               Cport::operator int is an integer typecast used for procuring
               the error code from when an instance of the serial port was
               constructed. The actual typecasting may or may not be
               necessary, but is recommended.

   Return value   Cport::operator int returns an error code from when the
                  instance of the serial port was constructed. See Table A-4
                  in Appendix A for a list of possible return values.

   See Also    Cport::Cport

   Example     Check for errors after instance of a serial port is
               constructed.

               int main(void)
               {

                  Cport com1(COM1, B9600, W8|S1|NONE, 1024, 512);

                     // The instance 'com1' is casted to an int to procure the
                     // error code.
                     //
                  if((int)com1 != NO_ERR)
                  {
                     switch(com1)
                     {
                        case RX_ALC:
                        case TX_ALC:
                        case GEN_ALC:
                           // allocation error
                           break;

                        case NO_UART:
                           // no UART
                           break;

                        default:
                           // all other errors
                           break;
                     }
                  }
                  ...continued

                                 5-5


   Cport::Handshake
   ------------------------------------------------------------------

   Function    Enables or disables handshaking (flow control ) for a serial
               port.

   Syntax      #include "cport.h"
               void Cport::Handshake(byte htype, unsigned thresh);

   Parameters

      htype  - Type of handshaking to be used. See Table A-5 in Appendix A
               for a list of handshaking components.

      thresh - Receive queue threshold.

   Remarks     Cport::Handshake enables or disables software and/or hardware
               handshaking for the serial port instance. In software
               handshaking, XON and XOFF characters are used to suspend and
               resume communications. Hardware handshaking uses any or all of
               the DTR, DSR, RTS, CTS and DCD lines to suspend and resume
               communications. Thresh determines when the receiver will
               assert and inhibit the corresponding handshaking. If no
               receive handshaking is specified (RTS, DTR or S_RX), the
               threshold is not used and may be set to zero.

   See also    Cport::Param, Cport::Cport, Cport::Tx

   Example     If COM1 is successfully opened, turn on some hardware
               handshaking and set the receiver threshold to 3/4 of the
               receiver's full size. The transmitter will not transmit unless
               both DSR and DCD are asserted. The receiver will inhibit DTR
               if the receive queue length exceeds the threshold.

               int main(void)
               {

                  Cport com1(COM1, B9600, W8|S1|NONE, 1024, 512);
                  if((int)com1 != NO_ERR)
                  {
                     // error
                  }

                  com1.Handshake(DSR|DTR|DCD, 768);

                  ...continued

                  return(0);
               }

                                 5-6


   Cport::Param
   ------------------------------------------------------------------

   Function    Retrieves the parameters of a serial port.

   Syntax      #include "cport.h"
               Cport::Param(CPARAM& param)

   Parameters

      param  - Reference to a type CPARAM where the parameters will be
               stored.

   Remarks     Cport::Param retrieves the parameters and handshaking status
               of the serial port instance and stores them in a type CPARAM.

   See also    CPARAM, Cport::Cport

   Example     Create an instance of a serial port with the same
               configuration as one that already exists.

               Cport OpenCopy(int id, Cport& copyme)
               {
               CPARAM param;

                  copyme.Param(param);
                  param.id = id;
                  return(Cport(param));
               }


   Cport::Baud
   ------------------------------------------------------------------

   Function    Changes the baud rate of a serial port.

   Syntax      #include "cport.h"
               void Cport::Baud(int baud);

   Parameters

      baud   - Value that defines the baud rate. The actual value is the
               baud rate divisor, which allows for possibility of custom baud
               rates. The baud rate divisor = f / (16 * baud rate) where
               f is 1.8432e+6. See Table A-2 in Appendix A for a list of
               predefined baud rate divisors.

   Remarks     Cport::Baud changes the baud rate of the serial port instance.
               The parameter baud is the baud rate divisor that determines
               the baud rate.

   See also    Cport::Cport, Cport::Param, Cport::Mode

                                 5-7


   Example     Set the specified serial port to a new baud rate.

               #define NBAUD   4

               int SetBaud(Cport& com, unsigned n)
               {
               int baud[NBAUD] = { B9600, B2400, B1200, B300 };

                  if(n < NBAUD)
                  {
                     com.Baud(baud[n]);
                     return(0);
                  }
                  else
                     return(-1);
               }


   Cport::Mode
   ------------------------------------------------------------------

   Function    Changes the word length, number of stop bits and parity of a
               serial port.

   Syntax      #include "cport.h"
               void Cport::Mode(byte mode);

   Parameters

      mode   - Bit ORed value defining the word length, number of stop bits
               and the parity. See Table A-3 in Appendix A for a list of mode
               components.

   Remarks     Cport::Mode changes the word length, number of stop bits and
               parity of the serial port instance. The parameter mode
               determines the word length, number of stop bits and parity of
               the serial port instance. Bits 0 and 1 determine the word
               length, bit 2 determines the number of stop bits, bit 3 enables
               parity and bits 4 and 5 determine the type of parity check.

   See also    Cport::Cport, Cport::Param, Cport::Baud

   Example     Set the serial port to a new mode.

               #define NMODE   2

               int SetMode(Cport& com, unsigned n)
               {
               int mode[NMODE] = { W8|S1|NONE, W7|S1|EVEN };

                  if(n < NMODE)
                  {
                     com.Mode(mode[n]);
                     return(0);
                  }
                  return(-1);
               }
                                 5-8


   Cport::RxQ
   ------------------------------------------------------------------

   Function    Resizes the receive queue of a serial port.

   Syntax      #include "cport.h"
               unsigned Cport::RxQ(unsigned size);

   Parameters

      size   - New receive queue size.

   Remarks     Cport::RxQ resizes the receive queue of the serial port
               instance. The memory currently allocated for the receive queue
               is freed and new memory is allocated. If Cport::RxQ is unable
               to allocate the specified amount memory, it will try to
               reallocate memory for the previous size. Cport::RxQ returns
               the new queue size. If memory was successfully allocated for
               the new size, the return value will be size. If the previous
               size is reallocated, the return value will be the previous
               size. If no memory could be allocated, Cport::RxQ returns
               zero.

               No data can be received while the new receive queue is being
               resized. However, data in the transmit queue will continue to
               be transmitted normally.

   Return value   Cport::RxQ returns the new receive queue size.

   See also    Cport::TxQ, Cport::Cport

   Example     Enlarge the receive queue for a file transfer.

               #define LARGE_RX   4096
               int ReceiveFile(Cport& com, const char *filename)
               {
               CPARAM param;

                  com.Param(param);
                  if(com.RxQ(LARGE_RX) != LARGE_RX)
                     return(-1);

                     ... transfer file here

                     // Restore original size
                  if(com.RxQ(param.rxQ) != param.rxQ)
                     return(-2);
                  else
                     return(0);
               }

                                 5-9


   Cport::TxQ
   ------------------------------------------------------------------

   Function    Resizes the transmit queue of a serial port.

   Syntax      #include "cport.h"
               unsigned Cport::TxQ(unsigned size);

   Parameters

      size   - New transmit queue size.

   Remarks     Cport::TxQ resizes the transmit queue of the serial port
               instance. The memory currently allocated for the transmit
               queue is freed and new memory is allocated. If Cport::TxQ is
               unable to allocate the specified amount memory, it will try
               to reallocate memory for the previous size. Cport::TxQ returns
               the new queue size. If memory was successfully allocated for
               the new size, the return value will be size. If the previous
               size is reallocated, the return value will be the previous
               size. If no memory could be allocated, Cport::TxQ returns zero.

               No data can be transmitted while the new transmit queue is
               being resized. However, data in the receive queue will
               continue to be received normally.

   Return value   ComTxQ returns the new transmit queue size.

   See also    Cport::RxQ, Cport::Cport

   Example     Enlarge the transmit queue for a file transfer.

               #define LARGE_TX   4096
               int TransmitFile(Cport& com, const char *filename)
               {
               CPARAM param;

                  com.Param(param);
                  if(com.TxQ(LARGE_TX) != LARGE_TX)
                     return(-1);

                     ... transfer file here

                     // Restore original size
                  if(com.TxQ(param.txQ) != param.txQ)
                     return(-2);
                  else
                     return(0);
               }

                                 5-10


   Cport::Tx
   ------------------------------------------------------------------

   Function    Transmitter control.

   Syntax      #include "cport.h"
               int Cport::Tx(int cmnd);

   Parameters

      cmnd   - Determines the action to be taken on the transmitter See
               Table A-9 in Appendix A for a list of transmitter options.

   Remarks     Cport::Tx  allows advanced control of the Cport transmitter
               The transmitter can be turned off and on to suspend and resume
               transmissions. This function can be very useful when
               implementing your own handshaking scheme. In addition, it can
               inform the output functions to transmit directly when the
               transmitter is turned off.

   Return value   Cport::Tx returns the previous status of the transmitter.

   See also    Cport::Handshake, Cport::Cport, Cport::Param

   Example     Put a priority character directly  to the  serial port.

               void PriorityPutc(Cport& com, char c)
               {
               int tx;

                  tx = com.Tx(TX_DIRECT | OFF);
                  com.Put(c);
                  com.Tx(tx);
               }


   Cport::NS550
   ------------------------------------------------------------------

   Function    NS16550 UART setup.

   Syntax      #include "cport.h"
               void Cport::NS550(int trigger);

   Parameters

      trigger - Trigger threshold for the UART receive fifo. See Table A-12
               in Appendix A for a list of trigger levels.

   Remarks     If Cport detects an NS16550 UART when a serial port is opened,
               Cport automatically takes advantage of it's advanced capabilities.

               The receive fifo threshold is the number of bytes in the receive
               fifo that will cause an interrupt to be generated. By default,
               the receive fifo threshold is set to 14 bytes. Cport::NS550
               allows this receive fifo trigger threshold to be changed.

                                 5-11


   See Also    Cport::Uart

   Example     If the specified serial port is an NS16550, set the trigger
               level to 1 byte.

               void SetThreshIf550(Cport& com)
               {
                  if(com.Uart() == NS16550)
                     com.NS550(T550_1);
               }



   Cport::Turbo
   ------------------------------------------------------------------

   Function    Disables/re-enables high priority interrupts.

   Syntax      #include "cport.h"
               static void Cport::Turbo(int options);

   Parameters

      options - Bit mask of options. See Table A-6 in Appendix A for a list
               of turbo options.

   Remarks     During high speed data exchanges certain events that cause
               high priority interrupts can impede serial communications and
               possibly cause (over run) errors. This is especially true of
               the timer, which periodically uses extra time, and the
               keyboard, if keys are pressed.

               Cport::Turbo disables selected high priority interrupts or
               restores all of them. The high priority interrupts should
               never be disabled permanently or for long periods of time. The
               timer interrupt is not actually disabled but divert, allowing
               the system clock to continue to update. All other options are
               actually disabled when specified. Cport::Turbo is a static
               function. Although not very useful, it can be called prior to
               and/or independent of any instance of a serial port by
               specifying it's full name: Cport::Turbo(options).

   Example     Disable the keyboard and divert the timer while a block is
               transferred at high speed.

                                 5-12


               #include <time.h>
               #define BLK_SZ 128

               int GetBlock(Cport& com, byte* block, clock_t timeout)
               {
               int rv;

                     // assume 115200 baud
                     //
                  com.Turbo(TIMER | KEYBOARD);
                  timeout += clock();
                  while(com.LenRx() < BLK_SZ)
                  {
                     if(clock() > timeout)
                     {
                        com.Turbo(OFF);
                        return(0);
                     }
                  }
                  rv = com.In(block, BLK_SZ);
                  com.Turbo(OFF);
                  return(rv);
               }
                                 5-13


   Input Functions
   ---------------

   Basic

      Cport::Get gets a character or string of characters from the receive
      queue.

      Cport::In gets a block of data from the receive queue.

      Cport::FlushRx flushes the receive queue and receiver.

      Cport::LenRx calculates the number of characters/bytes in the receive
      queue.


   Intermediate

      Cport::Peek returns a copy of the head character/byte without removing
      it from the receive queue.

      Cport::RxScan scans the receive queue for a specified character.

                                 5-14


   Cport::Get
   ------------------------------------------------------------------

   Function    Fetches a character or string of characters from a serial
               port's receive queue.

   Syntax      #include "cport.h"
               char* Cport::Get(char *str, int maxc, char termc = '\n');

               or

               char Cport::Get();

   Parameters

      str    - Pointer to the buffer where the string of characters will be
               stored.

      maxc   - Maximum number of characters to fetch.

      termc  - Termination character. Cport::Get will return if this
               character is encountered.

   Remarks     Cport::Get fetches a character or string of characters from
               the serial port instance's receive queue.

               If Cport::Get is called with no parameters, it will fetch one
               character from the head of the serial port instance's receive
               queue. If there are no characters in the receive queue,
               Cport::Get returns a NULL character ('\0').

               If Cport::Get is called with parameters, it fetches a string
               of characters from the serial port instance's receive queue.
               The string will be stored in str. Str must be at least
               maxc + 1 characters long to allow for the NULL terminator.
               Cport::Get will return on the first occurrence of one of
               three conditions: 1) the character termc is encountered;
               2) maxc characters are reached; or 3) no more characters are
               available in the receive queue.

   Return value   When Cport:Get is called with no parameters, on success
                  it returns the character from the receive queue. If it
                  fails, it returns a NULL character ('\0'). When it is called
                  with parameters, Cport::Get returns a pointer to the NULL
                  terminated string.

   See also    Cport::In, Cport::LenRx, Cport::Put

                                 5-15


   Example     Get a measurement from the specified instrument if one is
               ready.

               #define MEAS_SIZ   24
               char* GetMeasurment(Cport& instrument, char* buf)
               {
                  if(instrument.LenRx() > MEAS_SIZ)
                  {
                     instrument.Get(buf, MEAS_SIZ, '\n');
                     return(buf);
                  }
                  else
                     return(NULL);
               }

   Example     Get a character from the modem and test if it is a start of
               header control character.

               #define SOH 1
               int CheckForSOH(Cport& modem)
               {
               char c;

                  c = modem.Get();
                  return(c == SOH);
               }


   Cport::In
   ------------------------------------------------------------------

   Function    Fetches a block of bytes from a serial port's receive queue.

   Syntax      #include "cport.h"
               unsigned Cport::In(void *abyte, unsigned nbyte);

   Parameters

      abyte  - Pointer to a buffer where the block of bytes will be stored.

      nbyte  - Number of bytes to get from the receive queue.

   Remarks     Cport::In fetches a block of bytes from the serial port
               instance's receive queue and stores it in abyte. Cport::In
               will always fetch num_byte bytes unless not enough bytes are
               available. Cport::In is well suited for receiving binary data.

   Return value   Cport::In returns the number of bytes actually fetched.

   See also    Cport::Out, Cport::Get, Cport::LenRx

                                 5-16


   Example     Get a block of 1024 bytes from the serial port.

               #include <time.h>
               #define BLK_SZ    1024
               #define TIMEOUT   -1

               int GetBlock(Cport& datalink, byte* buf, clock_t timeout)
               {

                  timeout += clock();
                  while(datalink.LenRx() < BLK_SZ)
                  {
                     if(clock() > timeout)
                        return(TIMEOUT);
                  }
                  return(datalink.In(buf, BLK_SZ));
               }


   Cport::FlushRx
   ------------------------------------------------------------------

   Function    Flushes a serial port's receiver and receive queue.

   Syntax      #include "cport.h"
               void Cport::FlushRx();

   Remarks     Cport::FlushRx deletes all existing characters/bytes in the
               serial port instance's receive queue and receiver.

   See also    Cport::LenRx, Cport::FlushTx

   Example     If a receive flush command is in order, flush the receiver.

               void RemoteCommand(Cport& com, int command)
               {
                  switch(command)
                  {
                     case TX_FLUSH:
                        com.FlushTx();
                        break;

                     case RX_FLUSH:
                        com.FlushRx();
                        break;

                     ...continued
                  }
               }

                                 5-17


   Cport::LenRx
   ------------------------------------------------------------------

   Function    Calculates the number of characters/bytes in the receive
               queue of a serial port.

   Syntax      #include "cport.h"
               unsigned Cport::LenRx();

   Remarks     Cport::LenRx calculates the number of characters/bytes
               in the receive queue of the serial port instance.

   Return value   Cport::LenRx returns the number of characters/bytes
                  residing in the receive queue.

   See also    Cport::FlushRx, Cport::LenTx

   Example     Get a measurement from the specified instrument if one is
               ready.

               #define MEAS_SIZ   24
               char* GetMeasurment(Cport& instrument, char* buf)
               {
                  if(instrument.LenRx() > MEAS_SIZ)
                  {
                     instrument.Get(buf, MEAS_SIZ, '\n');
                     return(buf);
                  }
                  else
                     return(NULL);
               }


   Cport::Peek
   ------------------------------------------------------------------

   Function    Fetches a copy of the head character from a serial port's
               receive queue.

   Syntax      #include "cport.h"
               char Cport::Peek();

   Remarks     Cport::Peek fetches a copy of the head character from the
               serial port instance's receive queue. Cport::Peek will not
               remove the character from the queue.

   Return value   Cport::Peek returns the copy of the head character.

   See also    Cport::Get, Cport::RxScan

                                 5-18


   Example     Get the head character if it is a control character.

               #include <ctype.h>
               char GetIfControl(Cport& com)
               {
               char peek;

                  peek = com.Peek();
                  if(iscntrl(peek))
                     return(com.Get());
                  else
                     return('\0');
               }


   Cport::RxScan
   ------------------------------------------------------------------

   Function    Scans the receive queue of a serial port for a specific
               character.

   Syntax      #include "cport.h"
               unsigned Cport::RxScan(char c);

   Parameters

      c      - Character to scan for.

   Remarks     Cport::RxScan searches for the character c in the serial port
               instance's receive queue. If the character is not found,
               Cport::RxScan returns a zero. Otherwise, it returns the offset
               into the receive queue of the first occurrence of c starting
               at 1 for the head character. This is the number of characters
               that must be fetched to get all data up to and including the
               character scanned for.

   Return value   Cport::Peek returns the offset into the receive queue to
                  the first occurrence of c. If c does not exist,
                  Cport::RxScan returns a zero.

   See also    Cport::Peek, Cport::Get

   Example     Get the next line terminated with a '\n'.

               char *GetLine(Cport& com, char *buffer)
               {
               int n;

                  n = com.RxScan('\n');
                  if(n > 0 && n < 80)
                     return(com.Get(buffer, n, '\n'));
                  else
                     return(NULL);
               }
                                 5-19


   Output Functions
   ----------------


   Basic

      Cport::Put puts a  character or a string of characters to the transmit
      queue.

      Cport::Out puts a block of data to the transmit queue.

      Cport::FlushTx flushes the transmit queue and transmitter.

      Cport::LenTx calculates the number of characters/bytes in the transmit
      queue.


   Advanced

      Cport::TxWait pauses program execution until the transmitter has emptied.

                                 5-20


   Cport::Put
   ------------------------------------------------------------------

   Function    Puts a character or a string of characters into the serial
               port's transmit queue.

   Syntax      #include "cport.h"
               int Cport::Put(const char *str);

               or

               int Cport::Put(char c);

   Parameters

      str    - Pointer to the string to be put into the transmit queue.

      c      - Character to be put into the transmit queue.

   Remarks     Cport::Put puts a character (c) or a string of characters
               (str) into the serial port a instance's transmit queue to be
               transmitted. If the transmit queue becomes full, Cport::Put
               will not attempt to put any more characters in the queue.

   Return value   Cport::Put returns the actual number of characters put
                  into the transmit queue. For single characters, this value
                  will be either 0 or 1.

   See also   Cport::Out, Cport::Get, Cport::LenTx

   Example     Echo the keyboard to the serial port when fetching a
               keystroke.

               #include <conio.h>

               static Cport echo(COM2, B9600, W8|S1|NONE ,1024 , 64);

               char GetKey(void)
               {
               char c;

                  if(kbhit())
                  {
                     c = getch();
                     echo.Put(c);
                     return(c);
                  }
                  else
                     return('\0');
               }

                                 5-21


   Example   Dial a number on the modem.

               #include <string.h>

               void ModDial(Cport& modem, const char* number)
               {
               char dial[24] = "ATDT";

                  strcat(dial, number);
                  strcat(dial, "\r");
                  modem.Put(dial);
               }


   Cport::Out
   ------------------------------------------------------------------

   Function    Puts a block of bytes into a serial port's transmit queue.

   Syntax      #include "cport.h"
               unsigned Cport::Out(const void *abyte, unsigned nbyte);

   Parameters

      abyte  - Pointer to the block to be put into the transmit queue.

      nbyte  - Number of bytes to be put into the transmit  queue.

   Remarks     Cport::Out puts the block of bytes pointed to by abyte into
               the serial port instance's transmit queue to be transmitted.

   Return value   Cport::Out returns the number of bytes actually put into
                  the transmit queue.

   See also    Cport::In, Cport::Put, Cport::LenTx

   Example     Send a block of 128 bytes to the transmitter.

               #define BLK_SZ 128
               int SendBlock(Cport& com, byte* block)
               {
               int rv;

                  rv = com.Out(block, BLK_SZ);
                  if(rv < BLK_SZ)
                     return(-1);

                  else
                     return(0);
               }

                                 5-22

   Cport::FlushTx
   ------------------------------------------------------------------

   Function    Flushes a serial port's transmit queue.

   Syntax      #include "cport.h"
               void Cport::FlushTx();

   Remarks     Cport::FlushTx deletes any existing characters in the serial
               port instance's transmit queue.

   See also    Cport::FlushRx, Cport::LenTx

   Example     If a transmit flush command is in order, flush the transmit
               queue.

               void RemoteCommand(Cport& com, int command)
               {
                  switch(command)
                  {
                     case TX_FLUSH:
                        com.FlushTx();
                        break;

                     case RX_FLUSH:
                        com.FlushRx();
                        break;

                     ...continued
                  }
               }


   Cport::LenTx
   ------------------------------------------------------------------

   Function    Calculates the number of characters/bytes in a serial
               port's transmit queue.

   Syntax      #include "cport.h"
               unsigned Cport::LenTx();

   Remarks     Cport::LenTx calculates the number of characters/bytes
               in the serial port instance's transmit queue.

   Return value   Cport::LenTx returns the number of characters/bytes
                  in the transmit queue.

   See also    Cport::LenRx, Cport::FlushTx

   Example     Check if the transmitter has reached 3/4 of capacity.

               #define TX_SIZE      1024

               int IsAboveThresh(Cport& sprinter)
               {
                  return(sprinter.LenTx() > (TX_SIZE * 3 / 4));
               }
                                 5-23


   Cport::TxWait
   ------------------------------------------------------------------

   Function    Waits for a serial port's transmitter to empty

   Syntax      #include "cport.h"
               void Cport::TxWait();

   Remarks     When a transmit queue becomes empty, the UART may not have
               actually transmitted the last of the bytes. A program may need
               to know when all the data has actually been transmitted so
               that it may, for example, change the state of the hardware
               lines. Cport::TxWait will return after the UART has been
               emptied of data.

   See Also    Cport::LenTx

   Example     Send a string to a half duplex device. This examples assumes
               that the device is monitoring our RTS line to determine a
               transmit or receive state.

               void SendMessage(Cport device, const char* msg)
               {
                  device.Rts(ON);
                  device.Put(msg);
                  while(device.LenTx());
                  device.TxWait();
                  device.Rts(OFF);
               }

                                 5-24


   Status Functions
   ----------------


   Basic

      Cport::Error detects hardware and software errors.


   Intermediate

      Cport::Status returns the status of the software and input hardware lines.

      Cport::Rts  controls the RTS output line.

      Cport::Dtr controls the DTR output line.


   Advanced

      Cport::Out1 controls the general purpose OUT1 output line.

      Cport::Uart determines what type of UART chip is residing at a serial port.

                                 5-25


   Cport::Error
   ------------------------------------------------------------------

   Function    Determines if any errors have occurred on a serial port since
               the last call to Cport::Error.

   Syntax      #include "cport.h"
               unsigned Cport::Error();

   Remarks     Cport::Error determines if any errors are pending on the
               serial port instance. After a call to Cport::Error, the errors
               are cleared. Cport::Error returns a bit ORed error word. See
               Table A-7 on Appendix A for a list of bit definitions.

   Return value   If an error has occurred, Cport::Error returns an error
                  word. If no errors have occurred, it returns a 0.

   See also    Cport::Status

   Example     Determine the source of the error if one has occurred.

               #define HARDWARE   (PARITY | FRAMING | BREAK | RX_FIFO)

               void CheckForErrors(Cport& dvm)
               {
               unsigned err;

                  if((err = dvm.Error()) == 0)
                     return;

                  else if(err & OVERUN)
                  {
                     // over run error
                  }
                  else if(err & HARDWARE)
                  {
                     // hardware errors
                  }
                  else if(err & (TXFULL | RXFULL))
                  {
                     // queue errors
                  }
               }


   Cport::Status
   ------------------------------------------------------------------

   Function    Retrieves the status of a serial port's software and hardware
               lines.

   Syntax      #include "cport.h"
               unsigned Cport::Status();

                                 5-26


   Remarks     Cport::Status retrieves the status of the serial port
               instance's software and hardware lines. Cport::Status returns
               a bit ORed status word. See Table A-8 in Appendix A for a list
               of bit definitions.


   Return value   Cport::Status returns the status word of the software and
                  hardware lines.

   See also    Cport::Error, Cport::Rts, Cport::Dtr

   Example     Test if the modem is powered up and ready.

               #include <dos.h>

               int CheckModem(Cport& modem)
               {
                  modem.Dtr(ON);
                  delay(40);

                  return((modem.Status() & DSR) != 0);
               }


   Cport::Rts
   ------------------------------------------------------------------

   Function    Sets or clears a serial port's Request to Send line.

   Syntax      #include "cport.h"
               void Cport::Rts(byte on_off);

   Parameters

      on_off - Determines whether RTS is to be set or cleared. See Table A-10
               in Appendix A.

   Remarks     Cport::Rts sets or clears the serial port instance's RTS line,
               depending on the value of on_off. If the value of on_off is
               ON, RTS is asserted. If the value of on_off is OFF, RTS is
               inhibited. In many cases, this signal will be looked at by the
               remote device to determine if it is safe to transmit. This
               gives the programmer the ability to turn off the remote
               device's transmitter.

               NOTE: Cport::Rts should never be called when RTS hardware
               handshaking is enabled.

   See also    Cport::Dtr, Cport::Status, Cport::Handshake

                                 5-27


   Example     Put the device in an on or off line state. (Assumes the remote
               device will not send data without our RTS asserted)

               void OffLine(Cport& device)
               {
                  device.Rts(OFF);
               }
               void OnLine(Cport& device)
               {
                  device.Rts(ON);
               }


   Cport::Dtr
   ------------------------------------------------------------------

   Function    Sets or clears a serial port's Data Terminal Ready line.

   Syntax      #include "cport.h"
               void Cport::Dtr(byte on_off);

   Parameters

      on_off - Determines whether DTR is to be asserted or inhibited. See
               Table A-10 in Appendix A.

      Remarks  Cport::Dtr set or clears the serial port instance's DTR line,
               depending on the value of on_off. If the value of on_off is
               ON, DTR is asserted. If the value of on_off is OFF, DTR is
               inhibited. In many cases, this signal will be looked at by the
               remote device to determine if it is safe to transmit. This
               gives the programmer the ability to turn off the remote
               device's transmitter.

               NOTE: Cport::Dtr should never be called when DTR hardware
               handshaking is enabled.

   See also    Cport::Rts, Cport::Status, Cport::Handshake

   Example     Put the device in an on or off line state. (Assumes the remote
               device will not send data without our DTR asserted).

               void OffLine(Cport& device)
               {
                  device.Dtr(OFF);
               }
               void OnLine(Cport& device)
               {
                  device.Dtr(ON);
               }

                                 5-28


   Cport::Out1
   ------------------------------------------------------------------

   Function    Sets or clears a serial port's Out1 line.

   Syntax      #include "cport.h"
               void Cport::Out1(byte on_off);

   Parameters

      on_off - Determines whether OUT1 is to be asserted or inhibited. See
               Table A-10 in Appendix A.

   Remarks     Cport::Out1 sets or clears the serial port instance's general
               purpose OUT1 line depending on the value of on_off. If the
               value of on_off is ON, OUT1 is asserted. If the value of
               on_off is OFF, OUT1 is inhibited. OUT1 is a general purpose
               output sometimes utilized by a device for a special feature or
               reset.

   See also    Cport::Rts, Cport::Dtr

   Example     Reset a smart modem.

               void SmartReset(Cport& modem)
               {
                  modem.Out1(ON);
                  delay(50);
                  modem.Out1(OFF);
               }


   Cport::Uart
   ------------------------------------------------------------------

   Function    Determines the type of UART at a serial port.

   Syntax      #include "cport.h"
   int Cport::Uart();

   Remarks     Cport::Uart determines the type of UART chip that resides
               at the instance's serial port. See Table A-11 for a list of
               UART types.

   Return value   Cport::Uart returns a value representative of the type of
                  UART that was detected.

   See Also    Cport::NS550

   Example     If the serial port instance has an NS16550 UART, set the
               trigger level to 1 byte.

               void SetThreshIf550(Cport& com)
               {
                  if(com.Uart() == NS16550)
                     com.NS550(T550_1);
               }
                                 5-29


   Data Integrity
   --------------

   Intermediate

      Cport::Checksum calculates a byte checksum of a block of data.

      Cport::Crc16 calculates a 16 bit cyclic redundancy check (CRC) on a
      block of data.

      Cport::Crc32.calculates a 32 bit cyclic redundancy check (CRC) on a
      block of data.

                                 5-30


   Cport::Checksum
   ------------------------------------------------------------------

   Function    Performs a byte checksum calculation on a block of data.

   Syntax      #include "cport.h"
               static byte Cport::Checksum(const void *abyte, unsigned nbyte);

   Parameters

      abyte  - Pointer to the block on which the checksum is to be performed.

      nbyte  - Number of bytes in the block.

   Remarks     Cport::Checksum performs a byte checksum on the block of bytes
               pointed to by abyte. The checksum is calculated by summing all
               the bytes in the block.

   Return value   Cport::Checksum returns a one byte checksum.

   See also    Cport::Crc16, Cport::Crc32, Cport::In, Cport::Out

   Example     Verify that the actual checksum matches the received checksum.

               struct Xblock
               {
                  byte num;
                  byte _num;
                  byte data[128];
                  byte checksum;
               }block;

               int GetXblock(Cport& com, Xblock& block)
               {
                  com.In(&block, sizeof(Xblock));

                  if((com.Checksum(block.data, 128) - block.checksum) != 0)
                     return(-1);
                  else
                     return(0);
               }


   Cport::Crc16
   ------------------------------------------------------------------

   Function    Performs a 16 bit cyclic redundancy check on a block of data.

   Syntax      #include "cport.h"
               static unsigned ComCrc16(const void *abyte, unsigned nbyte);

   Parameters

      abyte  - Pointer to the block on which the 16 bit cyclic redundancy
               check is to be performed.

                                 5-31


      nbyte  - Number of bytes in the block.


   Remarks     Cport::Crc16 performs a 16 bit cyclic redundancy check on the
               block of data pointed to by abyte.

   Return value   Cport::Crc16 returns the 16 bit CRC value.

   See also    Cport::Crc32, Cport::Checksum, Cport::In, Cport::Out

   Example     Verify that the actual CRC matches the received CRC.

               struct Xblock{
                  byte num;
                  byte _num;
                  byte data[128];
                  unsigned crc;
                  }block;

               int GetXblock(Cport& com, Xblock& block)
               {
                  com.In(&block, sizeof(Xblock));


                     // Check the calculated CRC against the block CRC.
                     //
                  if(com.Crc16(block.data, 128) != block.crc)
                     return(-1);
                  else
                     return(0);
               }


   Cport::Crc32
   ------------------------------------------------------------------

   Function    Performs a 32 bit cyclic redundancy check on a block of data.

   Syntax      #include "cport.h"
               static unsigned long ComCrc32(const void *abyte, unsigned nbyte);

   Parameters

      abyte  - Pointer to the block on which the 32 bit cyclic redundancy
               check is to be performed.

      nbyte  - Number of bytes in the block.

   Remarks     Cport::Crc32 performs a 32 bit cyclic redundancy check on the
               block of data pointed to by abyte.

   Return value   Cport::Crc32 returns the 32 bit CRC value.

   See also    Cport::Crc16, Cport::Checksum, Cport::In, Cport::Out

                                 5-32


   Example     Verify that the actual CRC matches the received CRC.

               struct Packet {
                  byte num;
                  byte data[1024];
                  unsigned long crc;
                  }packet;

               int GetPacket(Cport& com, Packet& packet)
               {
                  com.In(&packet, sizeof(Packet));

                     // Check the calculated CRC against the packet's CRC.
                     //
                  if(com.Crc32(packet.data, 1024) != packet.crc)
                     return(-1);
                  else
                     return(0);
               }

                                 5-33


   Misc Functions
   --------------

   Advanced

      Cport::SetBreak sets a break condition.

      Cport::ClrBreak clears a break condition.

      Cport::Scratch writes to or reads from the UART's scratch register.

                                 5-34


   Cport::SetBreak
   ------------------------------------------------------------------

   Function    Set a break condition on a serial port.

   Syntax      #include "cport.h"
               void Cport::SetBreak();

   Remarks     Cport::SetBreak sets a break condition on the serial port
               instance. The break condition will stay in effect until a
               subsequent call to Cport::ClrBreak is made.

   See also    Cport::ClrBreak

   Example     If the an abort condition has been declared, set a break
               condition. When it clears, release the break condition.

               void Abort(Cport& com, int abrt)
               {
               static int brkflg;

                  if(abrt && !brkflg)
                     com.SetBreak();

                  else if(!abrt && brkflg)
                     com.ClrBreak();
               }


   Cport::ClrBreak
   ------------------------------------------------------------------

   Function    Clears a previously set break condition on a serial port.

   Syntax      #include "cport.h"
               void Cport::ClrBreak();

   Remarks     Cport::ClrBreak clears a previously set break condition on the
               serial port instance.

   See also    Cport::SetBreak

   Example     If the an abort condition has been declared, set a break
               condition. When it clears, release the break condition.

               void Abort(Cport& com, int abrt)
               {
               static int brkflg;

                  if(abrt && !brkflg)
                     com.SetBreak();

                  else if(!abrt && brkflg)
                     com.ClrBreak();
               }

                                 5-35


   Cport::Scratch
   ------------------------------------------------------------------

   Function    Writes a byte to, or reads a byte from the serial port's
               scratch register.

   Syntax      #include "cport.h"
               void Cport::Scratch(byte abyte);

               or

               byte Cport::Scratch();

   Parameters

      abyte  - The byte to be written to the scratch register.

   Remarks     If a parameter is specified, Cport::Scratch writes the byte
               value abyte to the serial port instance's UART scratch
               register. If Cport::Scratch is called with no parameters, it
               reads the byte in the UART scratch register. Not all UARTs
               have a scratch register.

   Example     Exchange a value with the scratch register.

               byte ScratchExchange(Cport& com, byte value)
               {
               byte rv;

                  rv = com.Scratch();      // read the scratch register
                  com.Scratch(value);   // write to the scratch register
                  return(rv);
               }

                                 6-1


File Transfer
=============

   Xmodem
   ------

      XmodemTx transmits a file using the Xmodem file transfer protocol.

      XmodemRx receives a file using the Xmodem file transfer protocol.

      Xcallback is the default callback function for XmodemTx and XmodemRx.

                                6-2


   XmodemTx
   ------------------------------------------------------------------

   Function    Transmits a file with the Xmodem file transfer protocol.

   Syntax      #include "xmodem.h"
               int XmodemTx(COM, const char* file,
                                          int (*cb)(int msg, XPARAM param));
               or
               int XmodemTx(Cport&, const char* file,
                                          int (*cb)(int msg, XPARAM param));
   Parameters

      COM    - Handle of the serial port (C).

      Cport  - Reference to a serial port instance (C++).

      file   - Path/name of the file to be transferred.

      cb     - Pointer to the callback function.

   Remarks     XmodemTx transmits the file file via the serial port specified
               by COM or Cport. It will make calls back to the function cb if
               one is specified. If you specify NULL for cb, a default
               callback function will be used. See the following discussion
               on the callback function for a complete explanation of the
               callback function.

   Return value   XmodemTx returns zero if the file was transferred
                  successfully. Otherwise, it returns non-zero. See Table
                  6-1 for a list of return codes.

   See also    XmodemRx, Xcallback

   Example     Transfer the file cport.zip via the modem. (C)

                                /* callback function prototype */
               int myCallback(int msg, XPARAM param);

               int main(void)
               {
               COM modem;
               int rv;

                  modem = ComOpen(COM1, B2400, W8|S1|NONE, 1024, 512);
                  if(comopen_errno != NO_ERR)
                     return(-comopen_errno);

                  rv = XmodemTx(modem, "cport.zip", myCallback);
                  ComClose(modem);
                  return(rv);
               }

                                 6-3


   Example     Transfer the file cport.zip via the modem. (C++)

                                             // callback function prototype
               int myCallback(int msg, XPARAM param);
               int main(void)
               {
                  Cport modem(COM1, B2400);  // uses default parameters
                  if((int)modem != NO_ERR)
                     return(-((int)modem));

                  return(XmodemTx(modem, "cport.zip", myCallback));
               }


   XmodemRx
   ------------------------------------------------------------------

   Function    Receives a file with the Xmodem file transfer protocol.

   Syntax      #include "xmodem.h"
               int XmodemRx(COM, const char* file,
                                          int (*cb)(int msg, XPARAM param));
               or
               int XmodemRx(Cport&, const char* file,
                                          int (*cb)(int msg, XPARAM param));

   Parameters

      COM    - Handle of the serial port (C).

      Cport  - Reference to a serial port instance (C++).

      file   - Path/name of the file to be transferred.

      cb     - Pointer to the callback function.



   Remarks     XmodemRx receives the file file via the serial port specified
               by COM or Cport. It will make calls back to the function cb
               if one is specified. If you specify NULL for cb, a default
               callback function will be used. See the following discussion
               on the callback function for a complete explanation of the
               callback function.



   Return value   XmodemTx returns zero if the file was transferred
                  successfully. Otherwise, it returns non-zero. See Table
                  6-1 for a list of return codes.

   See also    XmodemTx, Xcallback

                                 6-4


   Example     Receive the file cport.zip via the modem. (C)

                                        /* callback function prototype */
               int myCallback(int msg, XPARAM param);

               int main(void)
               {
               COM modem;
               int rv;

                  modem = ComOpen(COM1, B2400, W8|S1|NONE, 1024, 512);
                  if(comopen_errno != NO_ERR)
                     return(-comopen_errno);

                  rv = XmodemRx(modem, "cport.zip", myCallback);
                  ComClose(modem);
                  return(rv);
               }

   Example     Receive the file cport.zip via the modem. (C++)

                                         // callback function prototype
               int myCallback(int msg, XPARAM param);

               int main(void)
               {
                  Cport modem(COM1, B2400);  // uses default parameters
                  if((int)modem != NO_ERR)
                     return(-((int)modem));

                  return(XmodemRx(modem, "cport.zip", myCallback));
               }


   Xcallback
   ------------------------------------------------------------------

   Function    Default callback function.

   Syntax      #include "xmodem.h"
               int Xcallback(int msg, XPARAM param);

   Parameters

      msg    - Callback message number. (See Table 6-2).

      param  - Message specific parameter. (See Table 6-2 and 6-3)

   Remarks     Xcallback is the default Xmodem callback function. When NULL
               is specified as the callback function in a call to XmodemTx
               or XmodemRx, Xcallback will be used. Xcallback only keeps
               track of errors to decide if the transfer should be aborted.
               You can chain callback functions by specifying a callback
               function and then calling Xcallback directly. You would do
               this if you were only interested in the information provided

                                 6-5


               to the callback function and did not want to affect the
               functionality of the transfer.


   Return value   When a callback function returns zero, the transfer
                  continues. If it returns non-zero, the transfer is
                  canceled, and XmodemRx or XmodemTx will return with a
                  non-zero return code.

   See also    XmodemTx, XmodemRx

   Example     Use the default callback when receiving the file cport.zip
               via the modem. This results in a blind transfer.

               int main(void)
               {
               COM modem;
               int rv;

                  modem = ComOpen(COM1, B2400, W8|S1|NONE, 1024, 512);
                  if(comopen_errno != NO_ERR)
                     return(-comopen_errno);

                  rv = XmodemRx(modem, "cport.zip", NULL);
                  ComClose(modem);
                  return(rv);
               }

   Example     Establish a callback function for procuring information for
               screen updates only.

               int myCallback(int msg, XPARAM param)
               {
                  switch(msg)
                  {
                     case XM_BLOCKCHECK:
                        /* Update the screen */
                        break;

                     case XM_BLOCK:
                        /* Update the screen */
                        break;

                     case...
                  }
                     /* chain to the default callback for functionality
                      */
                  return(Xcallback(msg, param));
               }

   Callback Function
   ------------------------------------------------------------------
   Since it usually takes time to transfer a file, there must be a mechanism
   for monitoring and optionally canceling the transfer. To accomplish this,
   the Xmodem transmit and receive functions accept a parameter, which is a
   pointer  to a callback function. This function will be called at certain

                                 6-6


   points during the file transfer. Your callback function can be used to
   update the screen, cancel the transfer, etc. Your callback function must
   have the exact prototype:

   int function_name(int msg, XPARAM param);

   Msg is the message number that identifies why the callback was made.
   The value of param depends on the message. It provides additional
   information for a specific message. Anytime param is not used, it is set
   to zero. The following is a list of messages and their descriptions.

   XM_IDLE (0) - Idle time. This message is sent during idle time to give
      the callback the opportunity to do something, such as checking to see
      if the user wishes to cancel the transfer.

   XM_START (1) - Start of transfer. This message is sent, at most, one time.
      It signals that the transfer has been successfully prepared and will
      now attempt to make contact with the remote station.

   XM_BLOCKCHECK (2) - Block check determined. Once the block check has
      been determined, this message is sent to inform the callback if the
      block check will be checksum (param == 0) or CRC16 (param != 0). This
      message is sent, at most, one time during a transfer. It is mostly
      informative .

   XM_BLOCK (3) - New block transferred. This message is sent each time a new
      block (128 bytes) is successfully transferred. For this message, param
      contains the block number. This message is primarily an informative
      message.

   XM_EOT (4) - End of transmission. This message is sent when an end of
      transmission is being established. Usually there will be only one of
      these messages, however, if problems arise, the EOT may be retried.

   XM_DONE (5) - Transfer done. This message is sent at the end of a
      transmission whether the transmission was successful or canceled. It
      is sent exactly one time if XM_START was previously sent. Otherwise,
      it will not be sent.

   XM_ERROR (6) - Error detected. This message is sent when an error is
      detected in the data. Param contains the error code. The lower 12 bits
      of param is the bit ORed errors returned by the function ComError.
      The upper 4 bits is the extended Xmodem error code (not bit ORed).
      The extended Xmodem error code (upper 4 bits) should always be
      non-zero. The ComError bits (lower 12 bits) may or may not indicate
      errors. Usually the ComError portion of the error code takes precedence
      over the extended Xmodem code, since it is likely to be the source of
      the error. The extended Xmodem errors are explained here. See ComError
      or Cport::Error for information on the lower 12 bits of the error code:

   XE_BADBLOCK (0x1000) - Bad block. This error occurs when a block was
      determined to be corrupted. Occasional bad block errors may occur. If
      the transfer is not canceled by the callback function, Xmodem will
      attempt to recover from this error (usually succeeding) by retrying
      the block.

                                 6-7


   XE_BADCHECK (0x2000) - Bad block check. This error occurs when the block
      is not detected as bad (XE_BADBLOCK) but the block check (CRC or
      checksum) does not match the data. This error can only be detected
      when receiving a file.

   XE_TIMEOUT (0x3000) - Timeout. Xmodem timed out waiting for a block or
      for protocol exchange. If the callback function does not cancel the
      transfer, Xmodem will retry whatever timed out. Successful recovery
      from this error depends on the reason (usually unknown) for the timeout.

   XE_CANCEL (0x4000) - Transmission canceled. This message is sent when
      the transmission is canceled by either the callback function, by the
      remote station or for other internal reasons.


   Xmodem Tables of Values
   ------------------------------------------------------------------



               name        value       description
               -----------------------------------------------
               XR_NOERR    (0)         No error.
               XR_FILEERR  (1)         File error.
               XR_CANCEL   (2)         Transfer canceled.
               XR_ALLOC    (3)         Memory allocation error.

               Table 6-1 - XmodemRx/XmodemTx return values.



   name           value    description             XPARAM
   -------------------------------------------------------------------------
   XM_IDLE        (0)      Idle time.              0.
   XM_START       (1)      Start of transfer       0.
   XM_BLOCKCHECK  (2)      Block check determined  0 if checksum, 1 if CRC16.
   XM_BLOCK       (3)      New block transferred   Block number.
   XM_EOT         (4)      End of transmission     0.
   XM_DONE        (5)      Transfer complete       0.
   XM_ERROR       (6)      Error has been detected Error code.

                  Table 6-2 - Xmodem callback messages.



            name           value       description
            ------------------------------------------------------------
            XE_BADBLOCK    (0x1000)    Bad block.
            XE_BADCHECK    (0x2000)    Bad block check (CRC or checksum).
            XE_TIMEOUT     (0x3000)    Timeout.
            XE_CANCEL      (0x4000)    Transfer canceled.

               Table 6-3 - Extended Xmodem error codes.

                                 A-1


Appendix A
==========

                     name     value
                     -----------------------
                     * COM1   (PORT0 | IRQ4)
                     * COM2   (PORT1 | IRQ3)
                     * COM3   (PORT2 | IRQ4)
                     * COM4   (PORT3 | IRQ3)

                     PORT0    (0x03F8)
                     PORT1    (0x02F8)
                     PORT2    (0x03E8)
                     PORT3    (0x02E8)

                     IRQ2     (0x2000)
                     IRQ3     (0x3000)
                     IRQ4     (0x4000)
                     IRQ5     (0x5000)
                     IRQ6     (0x6000)
                     IRQ7     (0x7000)

                     BIOS0    (*(int far *)0x400000l)
                     BIOS1    (*(int far *)0x400002l)
                     BIOS2    (*(int far *)0x400004l)
                     BIOS3    (*(int far *)0x400006l)

                     * The COMx constants are usually sufficient.

                     Table A-1 - Serial port id.



                     name     value
                     ---------------
                     B115200  (1)
                     B57600   (2)
                     B38400   (3)
                     B19200   (6)
                     B9600    (12)
                     B7200    (16)
                     B4800    (24)
                     B3600    (32)
                     B2400    (48)
                     B2000    (58)
                     B1800    (64)
                     B1200    (96)
                     B600     (192)
                     B300     (384)
                     B150     (768)
                     B110     (1047)
                     B75      (1536)
                     B50      (2304)

                     Table A-2 - Baud rate divisors.

                                 A-2



                     name     value    description
                     ----------------------------------------
                     W8       (0x03)   8 bit words.
                     W7       (0x02)   7 bit words.
                     W6       (0x01)   6 bit words.
                     W5       (0x00)   5 bit words.

                     S1       (0x00)   1 stop bit.
                     S2       (0x04)   2 stop bits.

                     NONE     (0x00)   No parity.
                     ODD      (0x08)   Odd parity.
                     EVEN     (0x18)   Even parity.
                     MARK     (0x28)   Mark parity (logic 1).
                     SPACE    (0x38)   Space parity (logic 0).

                     WMASK    (0x03)   Word mask.
                     SMASK    (0x04)   Stop bit mask.
                     PMASK    (0x38)   Parity mask.

                     Table A-3 - Bit ORed mode components.



         name     value    description
         ---------------------------------------------------------------
         NO_ERR   (0)      No errors.
         OPENED   (1)      Serial port is already opened.
         BAD_ID   (2)      Invalid id parameter.
         NO_UART  (3)      No UART chip was detected.
         RX_ALC   (4)      Receive queue allocation error.
         TX_ALC   (5)      Transmit queue allocation error.
         MAX_PORT (6)      The maximum number of serial ports are opened.
         IRQ_CTN  (7)      The irq contends with another open serial port.
         GEN_ALC  (8)      General memory allocation error.

                     Table A-4 - Open error values.



                  name     value    description
                  ---------------------------------------------------
                  OFF      (0x00)   No handshaking.
                  DTR      (0x01)   The receiver uses DTR.
                  RTS      (0x02)   The receiver uses RTS.
                  S_RX     (0x04)   The receiver uses XON/XOFF.
                  CTS      (0x10)   CTS is checked by the transmitter.
                  DSR      (0x20)   DSR is checked by the transmitter.
                  DCD      (0x80)   DCD is checked by the transmitter.
                  S_TX     (0x08)   The transmitter honors XON/XOFF.
                  SOFT     (0x0C)   Same as  (S_RX | S_TX).
                  HARD1    (0x21)   Same as  (DTR | DSR).
                  HARD2    (0x12)   Same as  (RTS | CTS).

                     Table A-5 - Bit ORed handshaking options.

                                 A-3



                  name     value    description
                  -----------------------------------
                  TIMER    (0x01)   divert timer (irq0).
                  KEYBOARD (0x02)   disable keyboard (irq1).
                  CASCADE  (0x04)   disable irq2.
                  OFF      (0x00)   restore all interrupts.

                     Table A-6 - Turbo options.



                     name     value    description
                     -----------------------------------------
                     OVERUN   (0x0002) Overrun error.
                     PARITY   (0x0004) Parity error.
                     FRAMING  (0x0008) Framing error.
                     BREAK    (0x0010) Break detect.
                     RX_FIFO  (0x0080) Rx fifo error.
                     TXFULL   (0x0100) Transmit queue overflow.
                     RXFULL   (0x0200) Receive queue overflow.
                     (unused) (0xF000) Designated as unused.

                     Table A-7 - Bit ORed error code.



                  name     value    description
                  -----------------------------------------------
                  DCTS     (0x001)  Change in clear to send.
                  DDSR     (0x002)  Change in data set ready.
                  TERI     (0x004)  Trailing edge ring indicator.
                  DDCD     (0x008)  Change in data carrier detect.
                  CTS      (0x010)  Clear to send asserted.
                  DSR      (0x020)  Data set ready asserted.
                  RI       (0x040)  Ring indicator asserted.
                  DCD      (0x080)  Data carrier detect asserted.
                  S_TX_OFF (0x100)  Transmitter off (XOFF state).
                  U_TX_OFF (0x200)  Transmitter off (ComTx).
                  S_RX_OFF (0x400)  Receiver off (XOFF state).

                     Table A-8 - Bit ORed status word.



                  name        value    description
                  ----------------------------------------------
                  ON          (1)      Turns the transmitter on.
                  OFF         (0)      Turns the transmitter off.
                  TX_DIRECT   (0x2)    Use direct mode when off.

                     Table A-9 - Transmitter options.

                                 A-4


                  name        value    description
                  -------------------------------------
                  ON          (1)      Signal asserted.
                  OFF         (0)      Signal inhibited.

                     Table A-10 - On/off values.



                  name     value    description
                  --------------------------------------
                  INS8250  (1)      INS8250 or INS8250-B.
                  NS16450  (2)      NS16450 or INS8250A.
                  NS16550  (3)      NS16550.
                  I82510   (4)      82510 (Intel).

                        Table A-11 - UART types.



                  name     value    description
                  --------------------------------
                  T550_1   (0x00)   1 byte.
                  T550_4   (0x400   4 bytes.
                  T550_8   (0x80)   8 bytes.
                  T550_14  (0xC0)   14 bytes.

                  Table A-12- NS550 trigger thresholds.

                                 B-1


Appendix B
==========

   Compiling
   ---------
      1) Make sure the header file(s) are included in any modules (source
         files) which make calls to Cport library functions.

         Example: #include "cport.h"

      2) Make sure your compiler knows where to find the header file(s).

         Borland C/C++: bcc -c -Ic:\cport\include your_file

         Microsoft C/C++: cl /c /Ic:\cport\include your_file

         NOTE: cl will also look at the INCLUDE environment variable for
               the include directories.

         Example: set INCLUDE=c:\c600\include;c:\cport\include;

      3) Make sure your compiler is generating byte alignments when generating
         structures. This is only a concern when using Cport functions, which
         involve structures such as CPARAM. For Borland and Microsoft
         compilers, this is taken care of. If you are using another compiler,
         consult your user's manual on how to generate byte alignments.

         Borland C/C++: (uses byte alignment by default)

         Microsoft C/C++: cl /c /Zp1 /Ic:\cport\include your_file

   Linking
   -------
      1) Make sure the appropriate Cport library is included in the list of
         libraries. The last letter in the file name of the libraries
         indicates the memory model:

            cports.lib - small model
            cportm.lib - medium model
            cportc.lib - compact model
            cportl.lib - large model
            cporth.lib - huge model

      2) Make sure the linker knows where to find the library files.

   Borland C/C++: tlink /Lc:\cport\lib c0s objs, exe_name, map_name, cports cs

   Microsoft C/C++: link  objs, exe_name, map_name, cports slibce;

         NOTE: link looks at the LIB environment variable for the library
         directories:

         Example: set LIB=c:\c600\lib;c:\cport\lib;

                                 C-1


Appendix C
==========

Cport v2.0 Order Form

   Name: ___________________________________________________________

   Company: ________________________________________________________

   Address: ________________________________________________________

   City: _________________________________  State: _________________

   Zip Code: _________________  Phone # : __________________________

   CompuServe # : __________________________________________________

   How did you acquire Cport ? _____________________________________

   Compiler(s): ____________________________________________________

   Computer(s): ____________________________________________________

   Operating system(s): ____________________________________________


                 Single Licence .... $65.00

                 2 Licenses ........ $59.00 each

                 3 to 4 Licenses ... $54.00 each

                 5 to 9 licenses ... $48.00 each

                 10+ licenses ...... $41.00 each

                 Quantity          price each

   Subtotal      _________    X    __________   =    $________

   California residents add sales tax    ( 8.25% )   $________

   Shipping outside continental U.S. add ( $ 5.00)   $________

                                            Total:   $________
   All Payments Must be in U.S. Dollars

   Make check or money order payable to:    Bri Productions
                                            39120 Argonaut Way, Ste 772
                                            Fremont, CA 94538-1378

   Visa/Master Card#:___________________  Expiration Date:_________

   Signature (Credit card only):___________________________________

                                 C-2


We want to hear from you!
-------------------------
In order to improve Cport and add valuable features, we need to know what
features you need most. This information is important in order to provide
you with the best possible product. Please take a moment to answer the
following questions.

Indicate your need for the following features by checking the choice
which best describes your need for the feature:

                                 very    |  nice   |  don't
                               important | to have | need it
                              -----------  -------- ---------

      Multi port Serial Boards:   ____      ____      ____

  Board name(s) ______________

                 Modem support:   ____      ____      ____


          Zmodem file transfer:   ____      ____      ____


Other file transfer __________:   ____      ____      ____


Other file transfer __________:   ____      ____      ____


               Windows support:   ____      ____      ____


Other ________________________:   ____      ____      ____


Other ________________________:   ____      ____      ____


Other ________________________:   ____      ____      ____



   What other types of libraries would you find useful ? _____

   ___Game Port   ___Expanded Memory   ___Sound effects

   Others______________________________________________________

   Other Comments______________________________________________

   ____________________________________________________________

   ____________________________________________________________

Bri Productions, 39120 Argonaut Way, Ste 772, Fremont, CA 94538-1378
[phone]